diff --git a/README.md b/README.md index 64dc6a6..784ee92 100644 --- a/README.md +++ b/README.md @@ -103,3 +103,26 @@ Ideally you don't add stub pages, but sometimes it's better to just add a page a This page is just a stub that needs to be completed. You can `open a PR on the repo `_ to add more content to the page. :raw-html:`` ``` + +### How do I add grouped tabs with examples of commands for different shells? + +```rst +.. tabs:: + + .. code-tab:: bash Linux + + ssh root@10.11.99.1 + + .. code-tab:: bash macOS + + ssh root@10.11.99.1 + + .. code-tab:: bat Windows (CMD) + + ssh root@10.11.99.1 + + .. code-tab:: pwsh Windows (PowerShell) + + ssh root@10.11.99.1 + +``` diff --git a/requirements.txt b/requirements.txt index 882c86f..c34478f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,3 +5,4 @@ sphinxcontrib-htmlhelp==2.0.4 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-spelling==8.0.0 sphinxext-opengraph==0.9.1 +sphinx-tabs==3.4.4 diff --git a/src/conf.py b/src/conf.py index 40e87cd..4859d3c 100644 --- a/src/conf.py +++ b/src/conf.py @@ -69,6 +69,7 @@ "sphinxcontrib.spelling", "sphinxext.opengraph", "sphinx.ext.doctest", + "sphinx_tabs.tabs", ] rst_prolog = """ @@ -89,5 +90,6 @@ r"https://support\.remarkable\.com": "https://support.remarkable.com/s/", r"https://discord\.gg/ATqQGfu": "https://discord.com/invite/ATqQGfu", } - linkcheck_retries = 5 + +sphinx_tabs_valid_builders = ["linkcheck"] diff --git a/src/guide/access/backup.rst b/src/guide/access/backup.rst index 349382d..e16bb87 100644 --- a/src/guide/access/backup.rst +++ b/src/guide/access/backup.rst @@ -13,10 +13,35 @@ Backing Up Your Documents Documents managed by the built in software (xochitl) are stored in ``/home/root/.local/share/remarkable/xochitl/`` and you can use the following to back them up to your computer: -.. code-block:: shell +.. tabs:: - mkdir -p remarkable-backup/files - scp -r root@remarkable:/home/root/.local/share/remarkable/xochitl/ remarkable-backup/files/ + .. code-tab:: bash Linux + + mkdir -p remarkable-backup/files + scp -r \ + root@remarkable:/home/root/.local/share/remarkable/xochitl/ \ + remarkable-backup/files/ + + .. code-tab:: bash macOS + + mkdir -p remarkable-backup/files + scp -r \ + root@remarkable:/home/root/.local/share/remarkable/xochitl/ \ + remarkable-backup/files/ + + .. code-tab:: bat Windows (CMD) + + if not exist remarkable-backup\files mkdir remarkable-backup\files + scp -r ^ + root@remarkable:/home/root/.local/share/remarkable/xochitl/ ^ + remarkable-backup/files/ + + .. code-tab:: pwsh Windows (PowerShell) + + New-Item -ItemType Directory -Force -Path remarkable-backup/files + scp -r ` + root@remarkable:/home/root/.local/share/remarkable/xochitl/ ` + remarkable-backup/files/ Backing Up Your Configuration @@ -24,10 +49,35 @@ Backing Up Your Configuration Xochitl's configuration is stored in ``/home/root/.config/remarkable/xochitl.conf``. This contains the root password in plain text, assuming you haven't changed it on the device. -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + mkdir -p remarkable-backup + scp -r \ + root@remarkable:/home/root/.config/remarkable/xochitl.conf \ + remarkable-backup/ + + .. code-tab:: bash macOS + + mkdir -p remarkable-backup + scp -r \ + root@remarkable:/home/root/.config/remarkable/xochitl.conf \ + remarkable-backup/ + + .. code-tab:: bat Windows (CMD) + + if not exist remarkable-backup mkdir remarkable-backup + scp -r ^ + root@remarkable:/home/root/.config/remarkable/xochitl.conf ^ + remarkable-backup/ + + .. code-tab:: pwsh Windows (PowerShell) - mkdir -p remarkable-backup - scp -r root@remarkable:/home/root/.config/remarkable/xochitl.conf remarkable-backup/ + New-Item -ItemType Directory -Force -Path remarkable-backup + scp -r ` + root@remarkable:/home/root/.config/remarkable/xochitl.conf ` + remarkable-backup/ Backing Up Other Data ===================== diff --git a/src/guide/access/file-transfer.rst b/src/guide/access/file-transfer.rst index f60b42e..806377d 100644 --- a/src/guide/access/file-transfer.rst +++ b/src/guide/access/file-transfer.rst @@ -24,17 +24,76 @@ OpenSSH If you have OpenSSH installed, you can use `scp `_ from the command line to copy files to and from the device: -.. code-block:: shell - scp ./file.txt root@10.11.99.1:/home/root/file.txt - scp root@10.11.99.1:/home/root/file.txt ./file.txt +.. tabs:: + + .. code-tab:: bash Linux + + scp \ + ./file.txt \ + root@10.11.99.1:/home/root/file.txt + scp \ + root@10.11.99.1:/home/root/file.txt \ + ./file.txt + + .. code-tab:: bash macOS + + scp \ + ./file.txt \ + root@10.11.99.1:/home/root/file.txt + scp \ + root@10.11.99.1:/home/root/file.txt \ + ./file.txt + + .. code-tab:: bat Windows (CMD) + + scp ^ + ./file.txt ^ + root@10.11.99.1:/home/root/file.txt + scp ^ + root@10.11.99.1:/home/root/file.txt ^ + ./file.txt + + .. code-tab:: pwsh Windows (PowerShell) + + scp ` + ./file.txt ` + root@10.11.99.1:/home/root/file.txt + scp ` + root@10.11.99.1:/home/root/file.txt ` + ./file.txt You can also use `sftp `_ from the command line to copy files to and from the device: -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + echo put file.txt \ + | sftp root@10.11.99.1 + echo get file.txt \ + | sftp root@10.11.99.1 + + .. code-tab:: bash macOS + + echo put file.txt \ + | sftp root@10.11.99.1 + echo get file.txt \ + | sftp root@10.11.99.1 + + .. code-tab:: bat Windows (CMD) + + echo put file.txt ^ + | sftp root@10.11.99.1 + echo get file.txt ^ + | sftp root@10.11.99.1 + + .. code-tab:: pwsh Windows (PowerShell) - echo put file.txt | sftp root@10.11.99.1 - echo get file.txt | sftp root@10.11.99.1 + echo "put file.txt" ` + | sftp root@10.11.99.1 + echo "get file.txt" ` + | sftp root@10.11.99.1 PuTTY ----- diff --git a/src/guide/access/ssh.rst b/src/guide/access/ssh.rst index d43fc89..c815c5c 100644 --- a/src/guide/access/ssh.rst +++ b/src/guide/access/ssh.rst @@ -52,26 +52,74 @@ After you connect your device to your computer with a USB cable, it will setup a From your computer you can now use your SSH client to connect to your reMarkable using ``10.11.99.1`` as the hostname. -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + ssh root@10.11.99.1 + + .. code-tab:: bash macOS + + ssh root@10.11.99.1 - ssh root@10.11.99.1 + .. code-tab:: bat Windows (CMD) + + ssh root@10.11.99.1 + + .. code-tab:: pwsh Windows (PowerShell) + + ssh root@10.11.99.1 Connecting over Wifi -------------------- When your device is connected to Wifi, you can connect to it with SSH using the IP address(es) assigned by your router. Replace ```` in the following command with a valid IP Address for your device. See `Finding Your Device Password and IP Addresses`_ for information on how to find the IP address. -.. code-block:: shell +.. tabs:: - ssh root@ + .. code-tab:: bash Linux + + ssh root@ + + .. code-tab:: bash macOS + + ssh root@ + + .. code-tab:: bat Windows (CMD) + + ssh root@ + + .. code-tab:: pwsh Windows (PowerShell) + + ssh root@ Depending on your network configuration, your reMarkable may also be available via hostname like ``remarkable``, ``remarkable.local``, or ``remarkable.lan``. -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux - ssh root@remarkable - ssh root@remarkable.local - ssh root@remarkable.lan + ssh root@remarkable + ssh root@remarkable.local + ssh root@remarkable.lan + + .. code-tab:: bash macOS + + ssh root@remarkable + ssh root@remarkable.local + ssh root@remarkable.lan + + .. code-tab:: bat Windows (CMD) + + ssh root@remarkable + ssh root@remarkable.local + ssh root@remarkable.lan + + .. code-tab:: pwsh Windows (PowerShell) + + ssh root@remarkable + ssh root@remarkable.local + ssh root@remarkable.lan .. _ssh-key: @@ -102,14 +150,53 @@ The following command will generate a private and public SSH key pair: -f ~/.ssh/id_rsa_remarkable \ -N '' +.. tabs:: + + .. code-tab:: bash Linux + + ssh-keygen \ + -f ~/.ssh/id_rsa_remarkable \ + -N '' + + .. code-tab:: bash macOS + + ssh-keygen \ + -f ~/.ssh/id_rsa_remarkable \ + -N '' + + .. code-tab:: bat Windows (CMD) + + ssh-keygen ^ + -f %userprofile%\.ssh\id_rsa_remarkable ^ + -N '' + + .. code-tab:: pwsh Windows (PowerShell) + + ssh-keygen ` + -f ~/.ssh/id_rsa_remarkable ` + -N '' :raw-html:`
⚠️ The generated SSH key will not have a password. ⚠️` This is a minor security concern, as anybody who can access the file will be able to use it to access your device. You can generate one with a password by using the following command instead: -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + ssh-keygen -f ~/.ssh/id_rsa_remarkable + + .. code-tab:: bash macOS - ssh-keygen -f ~/.ssh/id_rsa_remarkable + ssh-keygen -f ~/.ssh/id_rsa_remarkable + + .. code-tab:: bat Windows (CMD) + + ssh-keygen -f %userprofile%\.ssh\id_rsa_remarkable + + .. code-tab:: pwsh Windows (PowerShell) + + ssh-keygen -f ~/.ssh/id_rsa_remarkable :raw-html:`
` @@ -122,34 +209,108 @@ If you are using `PuTTY `_, The following command will install your SSH public key on your device: -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + ssh-copy-id \ + -i ~/.ssh/id_rsa_remarkable \ + root@10.11.99.1 + + .. code-tab:: bash macOS + + ssh-copy-id \ + -i ~/.ssh/id_rsa_remarkable \ + root@10.11.99.1 - ssh-copy-id \ - -i ~/.ssh/id_rsa_remarkable \ - root@10.11.99.1 + .. code-tab:: bat Windows (CMD) + + ssh root@10.11.99.1 ^ + mkdir -p -m 700 /home/root/.ssh + type %userprofile%\.ssh\id_rsa_remarkable.pub ^ + | ssh root@10.11.99.1 ^ + tee -a /home/root/.ssh/authorized_keys + ssh root@10.11.99.1 ^ + chmod 600 /home/root/.ssh/authorized_keys + + .. code-tab:: pwsh Windows (PowerShell) + + ssh root@10.11.99.1 ` + mkdir -p -m 700 /home/root/.ssh + type ~/.ssh/id_rsa_remarkable.pub ` + | ssh root@10.11.99.1 ` + tee -a /home/root/.ssh/authorized_keys + ssh root@10.11.99.1 ` + chmod 600 /home/root/.ssh/authorized_keys :raw-html:`
⚠️ This will not work properly until OpenSSH 9.4. ⚠️` Due to a bug in ssh-copy-id this installs to the wrong location on the device on versions of OpenSSH older than 9.4. You can check your version of OpenSSH with the following command on your computer: -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + ssh -V + + .. code-tab:: bash macOS + + ssh -V + + .. code-tab:: bat Windows (CMD) - ssh -V + ssh -V + + .. code-tab:: pwsh Windows (PowerShell) + + ssh -V .. raw:: html

For these versions you can use the following commands to install your public key instead:

-.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + ssh root@10.11.99.1 \ + mkdir -p -m 700 /home/root/.ssh + cat ~/.ssh/id_rsa_remarkable.pub \ + | ssh root@10.11.99.1 \ + tee -a /home/root/.ssh/authorized_keys + ssh root@10.11.99.1 \ + chmod 600 /home/root/.ssh/authorized_keys + + .. code-tab:: bash macOS + + ssh root@10.11.99.1 \ + mkdir -p -m 700 /home/root/.ssh + cat ~/.ssh/id_rsa_remarkable.pub \ + | ssh root@10.11.99.1 \ + tee -a /home/root/.ssh/authorized_keys + ssh root@10.11.99.1 \ + chmod 600 /home/root/.ssh/authorized_keys + + .. code-tab:: bat Windows (CMD) + + ssh root@10.11.99.1 ^ + mkdir -p -m 700 /home/root/.ssh + type %userprofile%\.ssh\id_rsa_remarkable.pub ^ + | ssh root@10.11.99.1 ^ + tee -a /home/root/.ssh/authorized_keys + ssh root@10.11.99.1 ^ + chmod 600 /home/root/.ssh/authorized_keys - ssh root@10.11.99.1 \ - mkdir -p -m 700 /home/root/.ssh - cat ~/.ssh/id_rsa_remarkable.pub \ - | ssh root@10.11.99.1 \ - tee -a /home/root/.ssh/authorized_keys - ssh root@10.11.99.1 \ - chmod 600 /home/root/.ssh/authorized_keys + .. code-tab:: pwsh Windows (PowerShell) + + ssh root@10.11.99.1 ` + mkdir -p -m 700 /home/root/.ssh + type ~/.ssh/id_rsa_remarkable.pub ` + | ssh root@10.11.99.1 ` + tee -a /home/root/.ssh/authorized_keys + ssh root@10.11.99.1 ` + chmod 600 /home/root/.ssh/authorized_keys :raw-html:`
` @@ -159,7 +320,7 @@ SSH Config File =============== You can set up an alias that is easier to remember by adding the following lines to the ``~/.ssh/config`` file on your computer: -.. code-block:: +.. code-block:: text host remarkable Hostname 10.11.99.1 @@ -169,9 +330,23 @@ You can set up an alias that is easier to remember by adding the following lines This will allow you to simplify how you connect to your device over SSH. -.. code-block:: shell +.. tabs:: + + .. code-tab:: bash Linux + + ssh remarkable + + .. code-tab:: bash macOS + + ssh remarkable + + .. code-tab:: bat Windows (CMD) + + ssh remarkable + + .. code-tab:: pwsh Windows (PowerShell) - ssh remarkable + ssh remarkable External Resources ================== diff --git a/src/tech/factory-reset.rst b/src/tech/factory-reset.rst index 397a3d5..fb7376b 100644 --- a/src/tech/factory-reset.rst +++ b/src/tech/factory-reset.rst @@ -18,7 +18,17 @@ This will cause you to lose access to your device, unless you have an :ref:`SSH In order to factory reset the device you will need to do the following steps: 1. Uninstall any manually added third party software or modifications. -2. Uninstall toltec: ``toltecctl uninstall`` -3. Ensure that xochitl is enabled: ``systemctl enable --now xochitl`` +2. Uninstall toltec: + +.. code-block:: shell + + toltecctl uninstall + +3. Ensure that xochitl is enabled: + +.. code-block:: shell + + systemctl enable --now xochitl + 4. Perform two :ref:`system upgrades `. 5. Perform a factory reset through the UI. diff --git a/src/tech/tailscale.rst b/src/tech/tailscale.rst index bc5a95a..144e967 100755 --- a/src/tech/tailscale.rst +++ b/src/tech/tailscale.rst @@ -54,7 +54,7 @@ Tailscale has a basic built in "nc" which tunnels traffic over the tailnet. The recommended way to configure this is via OpenSSH's `config files `_: -.. code-block:: console +.. code-block:: text Host myalias User myuser