opencrypt.conf(5)

NAME
opencrypt — configuration file for opencrypt

DESCRIPTION

All parameters are set in /etc/opencrypt/opencrypt.conf. This file is used when building initrd and during boot. All parameters safely default to no or empty.

GLOBAL PARAMETERS

VERBOSE=0|1|2|3
    Defaults to 0. Logs will go in /run/initramfs/opencrypt.log. With a greater value you get more details. It is used while building inird and during boot. It is particularly useful to trace cryptsetup, ssh and wget/wget2/curl.

BOND=yes|no
    Defaults to no. If bonding interface is used and master interface must be switch around slaves. Needed if bonded networks do not communicate (such as ethernet/wifi).

WPASUPPLICANT=yes|no
    Defaults to no. Set to yes if you need wpa_supplicant for your WIFI.

WAITFOR=interface
    Defaults to empty. If empty opencrypt will wait for at least one interface to be up. If set to an interface name opencrypt will wait during boot for this interface to be up. It is usually only needed for a WIFI interface.

    Example: WAITFOR="wlan0"

OC_MODULES=module ...
    Defaults to empty. You can list here some modules to be copied in initrd. You can instead add them in /etc/initramfs-tools/modules. But modules listed here will be preloaded with modprobe which is needed for some functions such as nft. You should list modules needed for network setup and device filesystem access (WIFI, xfs, ...). You can check modules loaded on a running system with lsmod. Modules dm_mod and dm_crypt are always included by cryptsetup-initramfs.

    Examples:

    iwlwifi OC_MODULES="iwlwifi iwlmvm mac80211 cfg80211 libarc4"

    b43 OC_MODULES="b43 ssb"

    mediatek OC_MODULES="mt76 mt7921e mt7921_common mt792x_lib mt76_connac_lib mac80211 cfg80211 ccp libarc4"

FIREWALL=iptables|nftables
    Defaults to empty. If empty, no firewall will be set. If set to nftables or iptables opencrypt will setup a firewall before interfaces are up. Ruleset must not depend on a specific interface. Iptables ruleset must be set in /etc/opencrypt/iptables.conf for IPv4 and/or /etc/opencrypt/ip6tables.conf for IPv6. Nftables ruleset must be set in /etc/opencrypt/nftables.conf. A simple ruleset is provided in /usr/share/doc/opencrypt/examples/nftables.conf.

KEYBOARDKEYSLOT=slot number

REMOTEKEYSLOT=slot number
    Defaults to empty. You can specify key slots used for keyboard or remote keys from network/device. These parameters are used only for LUKS devices. If set the same slots will be used for all LUKS devices to open. So you must let them empty if you use different slots for your LUKS devices on this system. They are passed to cryptsetup with the --key-slot parameter. If empty all slots will be searched which could slow down (but only a bit) the boot. You can use same or different slots as you wish. But you should keep a separate slot for keyboard until your install is rock solid.

KEYBOARDTIMEOUT=seconds
    Defaults to empty (same as 0). You can set a timeout passed to cryptsetup when asking a keyboard password. This parameter is not used for loopAES devices. If empty or set to 0 cryptsetup will wait forever for an input. If set and if there is no keyboard input opencrypt will try again to get device or network keys. This way you have a chance to plugin a device/network you forget. You should set it to some value allowing a slow user to enter the password.

DEVICELABEL=regex

DEVICETYPE=regex
    Devices will be searched selecting DEVICELABEL or DEVICETYPE (but not both). DEVICELABEL is the name you give to a device or a partition. It will be matched with the LABEL and the PARTLABEL of a partition as shown by blkid. DEVICETYPE is the filesystem type such as ext4, vfat, xfs, ... If you let both of them empty, all not encrypted devices will be searched. Multiple values can be used with shell regex. You can use blkid to find out exact values for your devices.

    Examples:

    DEVICELABEL="MYUSBKEY"

    DEVICETYPE="xfs" will search all xfs filesystems

    DEVICETYPE=xfs|ext.* will search xfs or all ext (2, 3, 4...) filesystems.

SEARCH PARAMETERS

Opencrypt can search external keys on various locations. Each location has its own block of parameters, starting with [SEARCH id], and followed by KEYID, REMOTEIP, REMOTEMODE, REMOTETIMEOUT, REMOTEOPT, REMOTEDIR, REMOTEFILE.

You need a block for each location to search. Opencrypt will search them in the order of appearance in the configuration file. If the same id is used in different blocks, only the first block will be used.

Opencrypt will search keys until all different KEYID are found. Keys will then be concatenated to create the key actually used by cryptsetyp. They will be concatenated in the order of appearance in the configuration file.

If all parameters are left empty, opencrypt will search unencrypted devices for some filenames and fallback asking a keyboard password. See opencrypt(7) for how filenames are formatted and where to install your remote keys.

All parameters default to empty.

[SEARCH searchid]
    searchid must be unique in the configuration file. If the same searchid is used in different blocks, only the first one will be used. It can be an arbitrary alphanumeric string to identify the search in the configuration and in the logs.

KEYID=keyid
    keyid can be the same for different SEARCH blocks. Opencrypt will use the first content found for a given keyid, searching first on devices or later on network. It can be an arbitrary alphanumeric string to identify the key in the configuration and in the logs.

REMOTEIP=IPv4|IPv6
    IPv4 or IPv6 to join

REMOTEMODE=device|ssh|wget|wget2|curl|arp
    device (default): opencrypt will search a key file on device only. ssh: opencrypt will use ssh to get a key file. wget: opencrypt will use https with wget to get a key file. wget2: opencrypt will use https with wget2 to get a key file. curl: opencrypt will use https with curl to get a key file. arp: opencrypt will use the arp address as the key, in this case REMOTEIP must be IPv4. If all REMOTEMODE are set to device opencrypt will not setup the network at all.

REMOTETIMEOUT=seconds
    You can set a timeout for ssh/wget/wget2/curl. If empty it will be set to 10 seconds. You should not set it to 0 else the ssh/wget/wget2/curl command could wait forever for the distant host.

REMOTEOPT=options
    Options to pass to ssh/wget/wget2/curl.

REMOTEDIR=directory
    URL prefix used with ssh/wget/wget2/curl. It will be used "as is", so it can include prefix for the basename. It must include an ending / if needed. For a device it must be relative to the device root.

REMOTEFILE=filename
    Set this parameter if you want to search a fixed filename. If empty the device found in crypttab will be used for formatting a filename specific for each crypted partition. See opencrypt(7) for how filenames are formatted and where to install your remote keys.

SEARCH BLOCK EXAMPLES

In this example opencrypt will search only 1 key on network on various hosts. The URL searched will be in order https://192.168.0.1/keys/key.txt, https://192.168.0.3/keys2/key.txt and https://192.168.0.2/keys/key3.txt. The first content found will be used for cryptsetup.

    [SEARCH first]
    KEYID="uuid"
    REMOTEIP="192.168.0.1"
    REMOTEMODE="wget"
    REMOTETIMEOUT=30
    REMOTEDIR="keys/"
    REMOTEFILE="key.txt"

    [SEARCH second]
    KEYID="uuid"
    REMOTEIP="192.168.0.3"
    REMOTEMODE="wget"
    REMOTETIMEOUT=30
    REMOTEDIR="keys2/"
    REMOTEFILE="key.txt"

    [SEARCH third]
    KEYID="uuid"
    REMOTEIP="192.168.0.2"
    REMOTEMODE="wget"
    REMOTETIMEOUT=30
    REMOTEDIR="keys/"
    REMOTEFILE="key3.txt"

In this example opencrypt will search 2 keys, control and uuid, first on devices then on network. Devices will be searched for /key.txt and /keys/UUID.key. Host 192.168.0.1 will be searched for key.txt via ssh on port 2822. Host 192.168.0.2 will be searched with the URL https://192.168.0.2/keys/UUID.key. If both control and uuid keys are found, opencrypt will concat them and use the result for cryptsetup.

    [SEARCH control1]
    KEYID="control"
    REMOTEIP="192.168.0.1"
    REMOTEMODE="ssh"
    REMOTETIMEOUT=10
    REMOTEOPT="-p 2822"
    REMOTEFILE="key.txt"

    [SEARCH control2]
    KEYID="control"
    REMOTEMODE="device"
    REMOTEFILE="key.txt"

    [SEARCH uuid1]
    KEYID="uuid"
    REMOTEIP="192.168.0.2"
    REMOTEMODE="wget"
    REMOTETIMEOUT=30
    REMOTEDIR="keys/"

    [SEARCH uuid2]
    KEYID="uuid"
    REMOTEMODE="device"
    REMOTEDIR="keys/"

SEE ALSO

opencrypt(7), some files in /usr/share/doc/opencrypt.

AUTHOR

This manual page was written by Michel Verdier <michel@verdier.net> for the Debian system (and may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 3 or any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3.