diff --git a/README.md b/README.md index da256ab..b56f6b1 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,80 @@ useradd --create-home --shell /bin/bash --user-group --groups wheel passwd ``` +### Networking + +By default the script configures plain ZFSBootMenu without networking nor an SSH server. If you're interested in SSH-ing into your ZFSBootMenu boot loader you're going to want to specify some of the following variables. + +#### IP address + +``` +ARCHZBM_NET_CLIENT_IP='' +ARCHZBM_NET_SERVER_IP='' +ARCHZBM_NET_GATEWAY_IP='' +ARCHZBM_NET_NETMASK='' +ARCHZBM_NET_HOSTNAME='' +ARCHZBM_NET_DEVICE='' +ARCHZBM_NET_AUTOCONF='' +``` + +By default none of the variables are set to any value and no networking will be available in ZFSBootMenu. If you want networking as in an IP address bound to a network interace set at least one of these variables or one of the [SSH](#ssh) variables listed further down. Setting one or more `ARCHZBM_NET_*` variables to an empty string is valid. If at least one variable is given either from this paragraph or from [SSH](#ssh) we're assuming that you want networking. Unspecified values and values set to the empty string `''` use defaults. + +For networking we rely on the [mkinitcpio-nfs-utils](https://archlinux.org/packages/core/x86_64/mkinitcpio-nfs-utils/) package with its `net` hook. Please refer to its [initcpio-install-net](https://gitlab.archlinux.org/archlinux/packaging/packages/mkinitcpio-nfs-utils/-/blob/main/initcpio-install-net) script file for usage hints on above variables. The hook implements a subset of the [ip Kernel Command Line argument](https://docs.kernel.org/admin-guide/nfs/nfsroot.html). + +Mapping between `net` hook field names and our shell variables is straightforward. Fields 8, 9 and 10 (DNS and NTP server addresses) from the official `ip` docs are unsupported in `net` hook. As such our hook has a total of 7 fields available for you to configure. + +``` ++-------------+------------------------+ +| net hook | This script | ++-------------+------------------------+ +| | ARCHZBM_NET_CLIENT_IP | +| | ARCHZBM_NET_SERVER_IP | +| | ARCHZBM_NET_GATEWAY_IP | +| | ARCHZBM_NET_NETMASK | +| | ARCHZBM_NET_HOSTNAME | +| | ARCHZBM_NET_DEVICE | +| | ARCHZBM_NET_AUTOCONF | ++-------------+------------------------+ +``` + +A valid example with a few fields populated may look like so: + +``` +ARCHZBM_NET_CLIENT_IP='10.10.10.2' +ARCHZBM_NET_GATEWAY_IP='10.10.10.1' +ARCHZBM_NET_NETMASK='255.255.255.0' +ARCHZBM_NET_DEVICE='eth0' +ARCHZBM_NET_AUTOCONF='none' +``` + +Note that in this example `ARCHZBM_NET_SERVER_IP` and `ARCHZBM_NET_HOSTNAME` are left unassigned. + +#### SSH + +If you want networking indicated by the fact that at least one of the `ARCHZBM_NET_*` variables is set or one of the `ARCHZBM_SSH_*` vars we assume that you want an SSH daemon as well. This comes in the form of a `dropbear` daemon with minimal configurability. Use the following variables to define Dropbear's behavior. + +``` +ARCHZBM_SSH_PORT='22' +ARCHZBM_SSH_KEEPALIVE_INTVL='1' +ARCHZBM_SSH_AUTH_KEYS='' +``` + +In `ARCHZBM_SSH_PORT` you specify Dropbear's listening port, this defaults to `22` if unconfigured or set to an empty string. With `ARCHZBM_SSH_KEEPALIVE_INTVL` you define at which interval Dropbear will send keepalive messages to an SSH client through the SSH connection. This defaults to `1` as in every `1` second a keepalive message is sent. + +Dropbear in this setup only supports key-based authentication, no password-based authentication. The value from `ARCHZBM_SSH_AUTH_KEYS` will be converted to a list of public SSH keys allowed to SSH into Dropbear as its default `root` user while ZFSBootMenu is running. The format of `ARCHZBM_SSH_AUTH_KEYS` is a single line where `authorized_keys` entries are split with double-commas: + +``` +ssh-rsa Eahajei8,,ssh-ed25519 kaeD0mas ... +``` + +This syntax crutch allows you to use the full range of Dropbear-supported `authorized_keys` stanzas, see [man 8 dropbear](https://man.archlinux.org/man/extra/dropbear/dropbear.8.en) for what's available. You may want to for example do: + +``` +command='zfsbootmenu',no-agent-forwarding ssh-rsa Eahajei8,,ssh-ed25519 kaeD0mas ... +``` + +Whether or not this is useful to you is another topic :) At least the functionality for stanzas is there by separating values in `ARCHZBM_SSH_AUTH_KEYS` with double-commas. + # Steps The script takes the following installation steps.