From 9615415308c35483f0517e0498b7dcb5ea937e2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Frieder=20Grie=C3=9Fhammer?= Date: Mon, 5 Jan 2015 13:07:48 +0100 Subject: [PATCH] using a three way split to divide seperate topics covered, rephrasing passages, fixing syntax --- docs/features/authorized-keys.rst | 30 ++++---- docs/index.rst | 1 + docs/user/accessing-nodes.rst | 123 ++++++++++++++---------------- docs/user/authentication.rst | 40 ++++++++++ 4 files changed, 113 insertions(+), 81 deletions(-) create mode 100644 docs/user/authentication.rst diff --git a/docs/features/authorized-keys.rst b/docs/features/authorized-keys.rst index 371e2a22..a005a065 100644 --- a/docs/features/authorized-keys.rst +++ b/docs/features/authorized-keys.rst @@ -1,21 +1,21 @@ -.. _add-ssh-keys: +Adding SSH global public keys +============================= -Adding SSH public keys -====================== +By using the package ``gluon-authorized-keys`` it is possible to add SSH public +keys to an image while compiling to permit root login. -By using the package ``gluon-authorized-keys`` it is possible to add -SSH public keys to an image to permit root login. +These keys work global on all nodes running the specific build - be careful not +to lose the private keys. -If you select this package, add a list of authorized keys to ``site.conf`` like this::: +If you select this package, add a list of authorized keys to ``site.conf`` like this:: - { - authorized_keys = { 'ssh-rsa AAA.... user1@host', - 'ssh-rsa AAA.... user2@host }, - hostname_prefix = ... - ... + { + authorized_keys = { 'ssh-rsa AAA.... user1@host', + 'ssh-rsa AAA.... user2@host }, + hostname_prefix = ... + ... + } -Existing keys in ``/etc/dropbear/authorized_keys`` will be preserved. +Existing keys in ``/etc/dropbear/authorized_keys`` will be preserved on update. -.. seealso:: - - For information how to reach foreign Nodes take a look at :ref:`accessing-nodes`. +.. seealso:: For Information how to add a SSH keys to single nodes see :doc:`/user/authentication`. diff --git a/docs/index.rst b/docs/index.rst index e4941b63..b8720a18 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ User Documentation user/getting_started user/site user/accessing-nodes + user/authentication user/faq Features diff --git a/docs/user/accessing-nodes.rst b/docs/user/accessing-nodes.rst index 8a19bc23..7d494497 100644 --- a/docs/user/accessing-nodes.rst +++ b/docs/user/accessing-nodes.rst @@ -1,87 +1,78 @@ -.. _accessing-nodes: - Accessing running nodes ======================= -Routers all have IPv6 addresses and within our batman network are treated like regular -computers - they are regular computers with a built-in WLAN device. One we know the -IPv6 address, one can access the device - to initiate a firmware update, perform -various sorts of maintenance for customised setups, or to just learn what is going on -when a node does not perform as expected. +Within the mesh network all Nodes have IPv6 addresses and are treated like regular +computers - with a built-in WLAN device. Once we know the IPv6 address, one can +access the device - to initiate a firmware update, perform various sorts of maintenance +for customized setups, or to just look what is going on when a node does not perform +as expected. -'Access' may mean a mere ping/traceroute to determine if a site can be reached. -To truly enter a machine, one will use ssh and the machines need to be prepared -for it with a password or a public key as explained below. Telnet access is only -possible when booting into safe-mode - which is explained elsewhere. +**Access** may mean a mere ``ping``/``traceroute`` to determine if a host can be reached. +To truly enter a machine, one will use SSH. How to prepare the Nodes for this either +via password or a SSH public key is described in :doc:`/user/authentication`. -Adding a password ------------------ +How to find the IPv6 address of a desired node +---------------------------------------------- -To set a password for any user of the routers, especially so for root, is not encouraged. -It comes handy, though, especially when loggin in from a machine that does not have your -private (secret) SSH key, e.g. from a gateway machine, but the very same is also its -disadvantage. +The IPv6 addresses of the nodes are static and derived from the MAC addresses. +Consequently, one needs to determine the IPv6 address only once per device. -To set a password the regular configuration screen with lua may already allow -specifying it. If that was disabled for security reasons, please - * boot into safe-mode - * telnet the router on 192.168.1.1 - * on the device - mount_root - passwd -SSH login will be possible after the start of dropbear, which is regularly performed -when running in normal mode. For users other than root, please perform as with any Linux -machine. +To find the IPv6 address one can: -.. seealso:: + * Look at the bottom of the device and find the MAC address there + * Directly connect via LAN-Cable and use the **next_node** addresses (if configured) + * + There are rules for an automated transcription of MAC addresses into IPv6 + addresses, you can find one implementation with some description at + `ben.akrin.com `_ - For Information how to add SSH public Keys see :ref:`add-ssh-keys`. + The procedure is basically an insertion of ff:ef in the middle, some bit + swapping and adding fe80:: as prefix. + * + If you know the IPv4 address of a client accessing the network through desired + node and perform ``batctl traceroute`` to that device from any other Node + in the mesh, the MAC address can be found in the last hub:: -How to find the IPv6 address of a router of interest ----------------------------------------------------- + $ batctl traceroute 10.135.17.193 -The IPv6 addresses of the routers are static and derived from -the MAC adresses. Consequently, one needs to determine the IPv6 -address only once per device. + traceroute to 10.135.17.193 (26:a4:3c:f0:b5:0a), 50 hops max, 20 byte packets + 1: 12:fe:ed:3b:3f:cb 22.418 ms 23.008 ms 24.980 ms + 2: 26:a4:3c:f0:b5:0a 28.733 ms 26.018 ms 22.403 ms + * + check response times - the nodes answering first are the ones connected the query host:: -To find the IPv6 address one can - * look at the bottom of the device and find a MAC address - * know the IPv4 number of a mobile client accessing the network through that device and perform - batctl traceroute on the IPv4 address assigned to that device. The last hub is the MAC address: - # batctl traceroute 10.135.17.193 - traceroute to 10.135.17.193 (26:a4:3c:f0:b5:0a), 50 hops max, 20 byte packets - 1: 12:fe:ed:3b:3f:cb 22.418 ms 23.008 ms 24.980 ms - 2: 26:a4:3c:f0:b5:0a 28.733 ms 26.018 ms 22.403 ms - * There are rules for an automated transcription of MAC addresses to IPv6 addresses, - automated e.g. at http://ben.akrin.com/?p=1347 - it is basically an insertion of ff:ef in the - middle and fe80:: as a prefix. - * check response times - the routers answering first are the ones connected the query host - # ping6 -I bat0 ff02::2 | head -n 5 - PING ff02::2(ff02::2) from fe80::ec88:71ff:fefa:40cc bat0: 56 data bytes - 64 bytes from fe80::ec88:71ff:fefa:40cc: icmp_seq=1 ttl=64 time=0.066 ms - 64 bytes from fe80::c24a:ff:fe42:2120: icmp_seq=1 ttl=255 time=26.6 ms (DUP!) - 64 bytes from fe80::fa1a:67ff:fe31:69ca: icmp_seq=1 ttl=255 time=27.1 ms (DUP!) - 64 bytes from fe80::12fe:edff:feaf:57cc: icmp_seq=1 ttl=255 time=27.5 ms (DUP!) - These addresses are local-link IPv6 addresses and can be contacted directly. - * It is expected these MAC addresses not to be exactly the same as the ones seen underneath - the device, since WLAN and Ethernet are different devices, and only the MAC addresses - of either are depicted, and there may be different MAC addreses for the WAN and LAN ports. + $ ping6 -I bat0 ff02::2 | head -n 5 + PING ff02::2(ff02::2) from fe80::ec88:71ff:fefa:40cc bat0: 56 data bytes + 64 bytes from fe80::ec88:71ff:fefa:40cc: icmp_seq=1 ttl=64 time=0.066 ms + 64 bytes from fe80::c24a:ff:fe42:2120: icmp_seq=1 ttl=255 time=26.6 ms (DUP!) + 64 bytes from fe80::fa1a:67ff:fe31:69ca: icmp_seq=1 ttl=255 time=27.1 ms (DUP!) + 64 bytes from fe80::12fe:edff:feaf:57cc: icmp_seq=1 ttl=255 time=27.5 ms (DUP!) + + These addresses are local-link IPv6 addresses and can be contacted directly. + +.. note:: + Since WLAN and Ethernet are different devices, each with it's own MAC address, + it is expected that these MAC addresses are not always exactly the same as + the ones seen underneath the device. Only one of either devices is depicted. Contacting the device --------------------- -For a mere ping, perform - # ping6 -I bat0 fe80::12fe:edff:feaf:57cc - PING fe80::12fe:edff:feaf:57cc(fe80::12fe:edff:feaf:57cc) from fe80::ec88:71ff:fefa:40cc bat0: 56 data bytes - 64 bytes from fe80::12fe:edff:feaf:57cc: icmp_seq=1 ttl=64 time=54.2 ms - 64 bytes from fe80::12fe:edff:feaf:57cc: icmp_seq=2 ttl=64 time=28.3 ms +For a mere ping, perform:: + + $ ping6 -I bat0 fe80::12fe:edff:feaf:57cc + + PING fe80::12fe:edff:feaf:57cc(fe80::12fe:edff:feaf:57cc) from fe80::ec88:71ff:fefa:40cc bat0: 56 data bytes + 64 bytes from fe80::12fe:edff:feaf:57cc: icmp_seq=1 ttl=64 time=54.2 ms + 64 bytes from fe80::12fe:edff:feaf:57cc: icmp_seq=2 ttl=64 time=28.3 ms + i.e. use ping6 instead of IPv4 ping and help with the interface. -For SSH, analogously do - # ssh fe80::12fe:edff:feaf:57cc%bat0 - The authenticity of host 'fe80::12fe:edff:feaf:57cc%bat0 (fe80::12fe:edff:feaf:57cc%bat0)' can't be established. - RSA key fingerprint is 53:5c:ac:f8:65:74:0b:cb:a4:67:26:3a:f5:65:2f:77. - Are you sure you want to continue connecting (yes/no)? +For SSH, analogously do:: + $ ssh fe80::12fe:edff:feaf:57cc%bat0 + The authenticity of host 'fe80::12fe:edff:feaf:57cc%bat0 (fe80::12fe:edff:feaf:57cc%bat0)' can't be established. + RSA key fingerprint is 53:5c:ac:f8:65:74:0b:cb:a4:67:26:3a:f5:65:2f:77. + Are you sure you want to continue connecting (yes/no)? diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst new file mode 100644 index 00000000..e5d43866 --- /dev/null +++ b/docs/user/authentication.rst @@ -0,0 +1,40 @@ +SSH Authentication +================== + +The methods described here can also be configured via :doc:`/features/configmode`. + +Telnet access is only possible when booting into safe-mode. How boot into safe-mode +is explained in the `openwrt wiki `_. + +SSH login will be possible after the start of dropbear, which is regularly performed +when running in normal mode. + +Adding a password +----------------- + +Setting a password for any user on the Nodes - especially for root - is *not encouraged*. +It comes handy, though, especially when logging in from via a remote machine that +does not have your own SSH private key, e.g. directly from a gateway machine. + +But passwords are always too short or too easy to guess/brutforce and therefore +mostly insecure. Always consider using SSH public keys. + +If setting a password via :doc:`/features/configmode` was disabled for security reasons, please: + + * boot into failsafe-mode + * telnet the node on ``192.168.1.1`` + * when connected:: + + $ mount_root + $ passwd + +For users other than root, please perform as you would do with any other Linux machine. + +Adding SSH public keys +---------------------- + +If it is not possible to set a SSH public key via :doc:`/features/configmode`, you +may use a temporary password or use the safe-mode to append your key to ``/etc/dropbear/authorized_keys`` +manually. + +.. seealso:: For Information how to add SSH public keys to the images while compiling see :doc:`/features/authorized-keys`