criu

package: criu

title: criu(8)

summary: checkpoint/restore in userspace

text:
# criu(8)

NAME

criu - checkpoint/restore in userspace

SYNOPSIS

criu command [option ...]

DESCRIPTION

criu is a tool for checkpointing and restoring running applications. It does this by saving their state as a collection of files (see the dump command) and creating equivalent processes from those files (see the restore command). The restore operation can be performed at a later time, on a different system, or both.

OPTIONS

Most of the long flags can be prefixed with no- to negate the option (example: --display-stats and --no-display-stats).

Common options

Common options are applicable to any command.

-v[v...], --verbosity

Increase verbosity up from the default level. In case of short option, multiple v can be used, each increasing verbosity by one.

-vnum, --verbosity=num

Set verbosity level to num. The higher the level, the more output is produced. The following levels are available:

•-v0 no output;

•-v1 only errors;

•-v2 above plus warnings (this is the default level);

•-v3 above plus information messages and timestamps;

•-v4 above plus lots of debug.

--config file

Pass a specific configuration file to criu.

--no-default-config

Disable parsing of default configuration files.

--pidfile file

Write root task, service or page-server pid into a file.

-o, --log-file file

Write logging messages to a file.

--display-stats

During dump, as well as during restore, criu collects some statistics, like the time required to dump or restore the process, or the number of pages dumped or restored. This information is always saved to the stats-dump and stats-restore files, and can be shown using crit(1). The option --display-stats prints out this information on the console at the end of a dump or restore operation.

-D, --images-dir path

Use path as a base directory where to look for sets of image files.

--stream

dump/restore images using criu-image-streamer. See https://github.com/checkpoint-restore/criu-image-streamer for detailed usage.

--prev-images-dir path

Use path as a parent directory where to look for sets of image files. This option makes sense in case of incremental dumps.

-W, --work-dir dir

Use directory dir for putting logs, pidfiles and statistics. If not specified, path from -D option is taken.

--close fd

Close file descriptor fd before performing any actions.

-L, --libdir path

Path to plugins directory.

--enable-fs [fs[,fs...]]

Specify a comma-separated list of filesystem names that should be auto-detected. The value all enables auto-detection for all filesystems. Note: This option is not safe, use at your own risk. Auto-detecting a filesystem mount assumes that the mountpoint can be restored with mount(src, mountpoint, flags, options). When used, dump is expected to always succeed if a mountpoint is to be auto-detected, however restore may fail (or do something wrong) if the assumption for restore logic is incorrect. This option is not compatible with --external dev.

--action-script script

Add an external action script to be executed at certain stages. The environment variable CRTOOLS_SCRIPT_ACTION is available to the script to find out which action is being executed, and its value can be one of the following: pre-dump

run prior to beginning a dump

post-dump

run upon dump completion

pre-restore

run prior to beginning a restore

post-restore

run upon restore completion

pre-resume

run when all processes and resources are restored but tasks are stopped waiting for final kick to run. Must not fail.

post-resume

called at the very end, when everything is restored and processes were resumed

network-lock

run to lock network in a target network namespace

network-unlock

run to unlock network in a target network namespace

setup-namespaces

run once root task has just been created with required namespaces. Note it is an early stage of restore, when nothing is restored yet, except for namespaces themselves

post-setup-namespaces

called after the namespaces are configured

orphan-pts-master

called after master pty is opened and unlocked. This hook can be used only in the RPC mode, and the notification message contains a file descriptor for the master pty

query-ext-files

called after the process tree is stopped and network is locked. This hook is used only in the RPC mode. The notification reply contains file ids to be added to external file list (may be empty).

--unprivileged

This option tells criu to accept the limitations when running as non-root. Running as non-root requires criu at least to have CAP_SYS_ADMIN or CAP_CHECKPOINT_RESTORE. For details about running criu as non-root please consult the NON-ROOT section.

-V, --version

Print program version and exit.

-h, --help

Print some help and exit.

pre-dump

Performs the pre-dump procedure, during which criu creates a snapshot of memory changes since the previous pre-dump. Note that during this criu also creates the fsnotify cache which speeds up the restore procedure. pre-dump requires at least -t option (see dump below). In addition, page-server options may be specified.

--track-mem

Turn on memory changes tracker in the kernel. If the option is not passed the memory tracker get turned on implicitly.

--pre-dump-mode=mode

There are two mode to operate pre-dump algorithm. The splice mode is parasite based, whereas read mode is based on process_vm_readv syscall. The read mode incurs reduced frozen time and reduced memory pressure as compared to splice mode. Default is splice mode.

dump

Performs a checkpoint procedure.

-t, --tree pid

Checkpoint the whole process tree starting from pid.

-R, --leave-running

Leave tasks in running state after checkpoint, instead of killing. This option is pretty dangerous and should be used only if you understand what you are doing. Note if task is about to run after been checkpointed, it can modify TCP connections, delete files and do other dangerous actions. Therefore, criu can not guarantee that the next restore action will succeed. Most likely if this option is used, at least the file system snapshot must be made with the help of post-dump action script.

In other words, do not use it unless really needed.

-s, --leave-stopped

Leave tasks in stopped state after checkpoint, instead of killing.

--external type[id]:value

Dump an instance of an external resource. The generic syntax is type of resource, followed by resource id (enclosed in literal square brackets), and optional value (prepended by a literal colon). The following resource types are currently supported: mnt, dev, file, tty, unix. Syntax depends on type. Note to restore external resources, either --external or --inherit-fd is used, depending on resource type.

--external mnt[mountpoint]:name

Dump an external bind mount referenced by mountpoint, saving it to image under the identifier name.

--external mnt[]:flags

Dump all external bind mounts, autodetecting those. Optional flags can contain m to also dump external master mounts, s to also dump external shared mounts (default behavior is to abort dumping if such mounts are found). If flags are not provided, colon is optional.

--external dev[major/minor]:name

Allow to dump a mount namespace having a real block device mounted. A block device is identified by its major and minor numbers, and criu saves its information to image under the identifier name.

--external file[mnt_id:inode]

Dump an external file, i.e. an opened file that is can not be resolved from the current mount namespace, which can not be dumped without using this option. The file is identified by mnt_id (a field obtained from /proc/pid/fdinfo/N) and inode (as returned by stat(2)).

--external tty[rdev:dev]

Dump an external TTY, identified by st_rdev and st_dev fields returned by stat(2).

--external unix[id]

Tell criu that one end of a pair of UNIX sockets (created by socketpair(2)) with the given id is OK to be disconnected.

--external net[inode]:name

Mark a network namespace as external and do not include it in the checkpoint. The label name can be used with --inherit-fd during restore to specify a file descriptor to a preconfigured network namespace.

--external pid[inode]:name

Mark a PID namespace as external. This can be later used to restore a process into an existing PID namespace. The label name can be used to assign another PID namespace during restore with the help of --inherit-fd.

--freeze-cgroup

Use cgroup freezer to collect processes.

--manage-cgroups

Collect cgroups into the image thus they gonna be restored then. Without this option, criu will not save cgroups configuration associated with a task.

--cgroup-props spec

Specify controllers and their properties to be saved into the image file. criu predefines specifications for common controllers, but since the kernel can add new controllers and modify their properties, there should be a way to specify ones matched the kernel. spec argument describes the controller and properties specification in a simplified YAML form:

```
"c1":

 - "strategy": "merge"

 - "properties": ["a", "b"]
"c2":

 - "strategy": "replace"

 - "properties": ["c", "d"]
```

where c1 and c2 are controllers names, and a, b, c, d are their properties.

Note the format: double quotes, spaces and new lines are required. The strategy specifies what to do if a controller specified already exists as a built-in one: criu can either merge or replace such.

For example, the command line for the above example should look like this:

```
--cgroup-props "\"c1\":\n - \"strategy\": \"merge\"\n - \"properties\": [\"a\", \"b\"]\n \"c2\":\n - \"strategy\": \"replace\"\n - \"properties\": [\"c\", \"d\"]"
```

--cgroup-props-file file

Same as --cgroup-props, except the specification is read from the file.

--cgroup-dump-controller name

Dump a controller with name only, skipping anything else that was discovered automatically (usually via /proc). This option is useful when one needs criu to skip some controllers.

--cgroup-yard path

Instead of trying to mount cgroups in CRIU, provide a path to a directory with already created cgroup yard. Useful if you don’t want to grant CAP_SYS_ADMIN to CRIU. For every cgroup mount there should be exactly one directory. If there is only one controller in this mount, the dir’s name should be just the name of the controller. If there are multiple controllers comounted, the directory name should have them be separated by a comma. For example, if /proc/cgroups looks like this:

```
#subsys_name hierarchy num_cgroups enabled
cpu          1         1           1
devices      2         2           1
freezer      2         2           1
```

then you can create the cgroup yard by the following commands:

```
mkdir private_yard
cd private_yard
mkdir cpu
mount -t cgroup -o cpu none cpu
mkdir devices,freezer
mount -t cgroup -o devices,freezer none devices,freezer
```

--tcp-established

Checkpoint established TCP connections.

--tcp-close

Don’t dump the state of, or block, established tcp connections (including the connection is once established but now closed). This is useful when tcp connections are not going to be restored.

--skip-in-flight

This option skips in-flight TCP connections. If any TCP connections that are not yet completely established are found, criu ignores these connections, rather than errors out. The TCP stack on the client side is expected to handle the re-connect gracefully.

--evasive-devices

Use any path to a device file if the original one is inaccessible.

--page-server

Send pages to a page server (see the page-server command).

--force-irmap

Force resolving names for inotify and fsnotify watches.

--auto-dedup

Deduplicate "old" data in pages images of previous dump. This option implies incremental dump mode (see the pre-dump command).

-l, --file-locks

Dump file locks. It is necessary to make sure that all file lock users are taken into dump, so it is only safe to use this for enclosed containers where locks are not held by any processes outside of dumped process tree.

--link-remap

Allows to link unlinked files back, if possible (modifies filesystem during restore).

--timeout number

Set a time limit in seconds for collecting tasks during the dump operation. The timeout is 10 seconds by default.

--ghost-limit size

Set the maximum size of deleted file to be carried inside image. By default, up to 1M file is allowed. Using this option allows to not put big deleted files inside images. Argument size may be postfixed with a K, M or G, which stands for kilo-, mega, and gigabytes, accordingly.

--ghost-fiemap

Enable an optimization based on fiemap ioctl that can reduce the number of system calls used when checkpointing highly sparse ghost files. This option is enabled by default, and it can be disabled with --no-ghost-fiemap. An automatic fallback to SEEK_HOLE/SEEK_DATA is used when fiemap is not supported.

-j, --shell-job

Allow one to dump shell jobs. This implies the restored task will inherit session and process group ID from the criu itself. This option also allows to migrate a single external tty connection, to migrate applications like top. If used with dump command, it must be specified with restore as well.

--cpu-cap [cap[,cap...]]

Specify CPU capabilities to write to an image file. The argument is a comma-separated list of:

•none to ignore capabilities at all; the image will not be produced on dump, neither any check performed on restore;

•fpu to check if FPU module is compatible;

•ins to check if CPU supports all instructions required;

•cpu to check if CPU capabilities are exactly matching;

•all for all above set.

By default the option is set to fpu and ins.

--cgroup-root [controller:]/newroot

Change the root for the controller that will be dumped. By default, criu simply dumps everything below where any of the tasks live. However, if a container moves all of its tasks into a cgroup directory below the container engine’s default directory for tasks, permissions will not be preserved on the upper directories with no tasks in them, which may cause problems.

--lazy-pages

Perform the dump procedure without writing memory pages into the image files and prepare to service page requests over the network. When dump runs in this mode it presumes that lazy-pages daemon will connect to it and fetch memory pages to lazily inject them into the restored process address space. This option is intended for post-copy (lazy) migration and should be used in conjunction with restore with appropriate options.

--file-validation [mode]

Set the method to be used to validate open files. Validation is done to ensure that the version of the file being restored is the same version when it was dumped. The mode may be one of the following:

filesize

To explicitly use only the file size check all the time. This is the fastest and least intensive check.

buildid

To validate ELF files with their build-ID. If the build-ID cannot be obtained, chksm-first method will be used. This is the default if mode is unspecified.

--network-lock [mode]

Set the method to be used for network locking/unlocking. Locking is done to ensure that tcp packets are dropped between dump and restore. This is done to avoid the kernel sending RST when a packet arrives destined for the dumped process. The mode may be one of the following:

iptables

Use iptables rules to drop the packets. This is the default if mode is not specified.

nftables

Use nftables rules to drop the packets.

skip

Don’t lock the network. If --tcp-close is not used, the network must be locked externally to allow CRIU to dump TCP connections.

--allow-uprobes

Allow dumping when uprobes vma is present. When used on dump, this option is required on restore as well.

```
A uprobes vma is automatically created by the kernel once a uprobe is
triggered. This mapping is not removed even once the uprobe is deleted. So,
even if a process once had uprobes attached to it, and they're removed by
the time the process is dumped, this option is still required because criu
has no way of knowing whether there are active uprobes or not.
```

```
When using this option on restore, make sure the uprobes (if any) active on
the dumped processes are still active. Otherwise, when execution reaches
a uprobe'd location in any of the restored processes, that process will be
sent a SIGTRAP.
```

```
As an example, say a uprobe is set at function foo in the executable of the
process p_bar. Whenever execution in p_bar reaches function foo, the uprobe
is triggered. If the uprobe has been triggered at least once, then the kernel
will have created the uprobes vma. To dump p_bar, this option is
necessary. After dumping, say the uprobe is deleted. Now, on restoring with
this option, once execution reaches function foo, SIGTRAP will be sent to
the restored p_bar. Unless it has a signal handler installed for SIGTRAP,
it will be terminated and core dumped.
```

restore

Restores previously checkpointed processes.

--inherit-fd fd[N]:resource

Inherit a file descriptor. This option lets criu use an already opened file descriptor N for restoring a file identified by resource. This option can be used to restore an external resource dumped with the help of --external file, tty, pid and unix options. The resource argument can be one of the following:

•tty[rdev:dev]

•pipe[inode]

•socket[inode*]*

•file[mnt_id:inode]

•path/to/file

Note that square brackets used in this option arguments are literals and usually need to be escaped from shell.

-d, --restore-detached

Detach criu itself once restore is complete.

-s, --leave-stopped

Leave tasks in stopped state after restore (rather than resuming their execution).

-S, --restore-sibling

Restore root task as a sibling (makes sense only with --restore-detached).

--log-pid

Write separate logging files per each pid.

-r, --root path

Change the root filesystem to path (when run in a mount namespace). This option is required to restore a mount namespace. The directory path must be a mount point and its parent must not be overmounted.

--external type[id]:value

Restore an instance of an external resource. The generic syntax is type of resource, followed by resource id (enclosed in literal square brackets), and optional value (prepended by a literal colon). The following resource types are currently supported: mnt, dev, veth, macvlan. Syntax depends on type. Note to restore external resources dealing with opened file descriptors (such as dumped with the help of --external file, tty, and unix options), option --inherit-fd should be used.

--external mnt[name]:mountpoint

Restore an external bind mount referenced in the image by name, bind-mounting it from the host mountpoint to a proper mount point.

--external mnt[]

Restore all external bind mounts (dumped with the help of --external mnt[] auto-detection).

--external dev[name]:/dev/path

Restore an external mount device, identified in the image by name, using the existing block device /dev/path.

--external veth[inner_dev]:outer_dev@bridge

Set the outer VETH device name (corresponding to inner_dev being restored) to outer_dev. If optional @bridge is specified, outer_dev is added to that bridge. If the option is not used, outer_dev will be autogenerated by the kernel.

--external macvlan[inner_dev]:outer_dev

When restoring an image that have a MacVLAN device in it, this option must be used to specify to which outer_dev (an existing network device in CRIU namespace) the restored inner_dev should be bound to.

-J, --join-ns NS:{PID|NS_FILE}[,EXTRA_OPTS]

Restore process tree inside an existing namespace. The namespace can be specified in PID or NS_FILE path format (example: --join-ns net:12345 or --join-ns net:/foo/bar). Currently supported values for NS are: ipc, net, time, user, and uts. This option doesn’t support joining a PID namespace, however, this is possible using --external and --inheritfd. EXTRA_OPTS is optional and can be used to specify UID and GID for user namespace (e.g., --join-ns user:PID,UID,GID).

--manage-cgroups [mode]

Restore cgroups configuration associated with a task from the image. Controllers are always restored in an optimistic way — if already present in system, criu reuses it, otherwise it will be created. The mode may be one of the following:

none

Do not restore cgroup properties but require cgroup to pre-exist at the moment of restore procedure.

props

Restore cgroup properties and require cgroup to pre-exist.

soft

Restore cgroup properties if only cgroup has been created by criu, otherwise do not restore properties. This is the default if mode is unspecified.

full

Always restore all cgroups and their properties.

strict

Restore all cgroups and their properties from the scratch, requiring them to not present in the system.

ignore

Don’t deal with cgroups and pretend that they don’t exist.

--cgroup-yard path

Instead of trying to mount cgroups in CRIU, provide a path to a directory with already created cgroup yard. For more information look in the dump section.

--cgroup-root [controller:]/newroot

Change the root cgroup the controller will be installed into. No controller means that root is the default for all controllers not specified.

--tcp-established

Restore previously dumped established TCP connections. This implies that the network has been locked between dump and restore phases so other side of a connection simply notice a kind of lag.

--tcp-close

Restore connected TCP sockets in closed state.

--veth-pair IN=OUT

Correspondence between outside and inside names of veth devices.

-l, --file-locks

Restore file locks from the image.

--lsm-profile type:name

Specify an LSM profile to be used during restore. The type can be either apparmor or selinux.

--lsm-mount-context context

Specify a new mount context to be used during restore. This option will only replace existing mount context information with the one specified with this option. Mounts without the context= option will not be changed.

If a mountpoint has been checkpointed with an option like

```
context="system_u:object_r:container_file_t:s0:c82,c137"
```

it is possible to change this option using

```
--lsm-mount-context "system_u:object_r:container_file_t:s0:c204,c495"
```

which will result that the mountpoint will be restored with the new context=.

This option is useful if using selinux and if the selinux labels need to be changed on restore like if a container is restored into an existing Pod.

--auto-dedup

As soon as a page is restored it get punched out from image.

-j, --shell-job

Restore shell jobs, in other words inherit session and process group ID from the criu itself.

--cpu-cap [cap[,cap...]]

Specify CPU capabilities to be present on the CPU the process is restoring. To inverse a capability, prefix it with ^. This option implies that --cpu-cap has been passed on dump as well, except fpu option case. The cap argument can be the following (or a set of comma-separated values): all

Require all capabilities. This is default mode if --cpu-cap is passed without arguments. Most safe mode.

cpu

Require the CPU to have all capabilities in image to match runtime CPU.

fpu

Require the CPU to have compatible FPU. For example the process might be dumped with xsave capability but attempted to restore without it present on target CPU. In such case we refuse to proceed. This is default mode if --cpu-cap is not present in command line. Note this argument might be passed even if on the dump no --cpu-cap have been specified because FPU frames are always encoded into images.

ins

Require CPU compatibility on instructions level.

none

Ignore capabilities. Most dangerous mode. The behaviour is implementation dependent. Try to not use it until really required. For example, this option can be used in case --cpu-cap=cpu was used during dump, and images are migrated to a less capable CPU and are to be restored. By default, criu shows an error that CPU capabilities are not adequate, but this can be suppressed by using --cpu-cap=none.

--weak-sysctls

Silently skip restoring sysctls that are not available. This allows to restore on an older kernel, or a kernel configured without some options.

--lazy-pages

Restore the processes without filling out the entire memory contents. When this option is used, restore sets up the infrastructure required to fill memory pages either on demand when the process accesses them or in the background without stopping the restored process. This option requires running lazy-pages daemon.

--file-validation [mode]

Set the method to be used to validate open files. Validation is done to ensure that the version of the file being restored is the same version when it was dumped. The mode may be one of the following:

filesize

To explicitly use only the file size check all the time. This is the fastest and least intensive check.

buildid

To validate ELF files with their build-ID. If the build-ID cannot be obtained, chksm-first method will be used. This is the default if mode is unspecified.

--skip-file-rwx-check

Skip checking file permissions (r/w/x for u/g/o) on restore.

--allow-uprobes

Required when dumped with this option. Refer to this option in the section on dumping for more details.

check

Checks whether the kernel supports the features needed by criu to dump and restore a process tree.

There are three categories of kernel support, as described below. criu check always checks Category 1 features unless --feature is specified which only checks a specified feature.

Category 1

Absolutely required. These are features like support for /proc/PID/map_files, NETLINK_SOCK_DIAG socket monitoring, /proc/sys/kernel/ns_last_pid etc.

Category 2

Required only for specific cases. These are features like AIO remap, /dev/net/tun and others that are only required if a process being dumped or restored is using those.

Category 3

Experimental. These are features like task-diag that are used for experimental purposes (mostly during development).

If there are no errors or warnings, criu prints "Looks good." and its exit code is 0.

A missing Category 1 feature causes criu to print "Does not look good." and its exit code is non-zero.

Missing Category 2 and 3 features cause criu to print "Looks good but ..." and its exit code is be non-zero.

Without any options, criu check checks Category 1 features. This behavior can be changed by using the following options:

--extra

Check kernel support for Category 2 features.

--experimental

Check kernel support for Category 3 features.

--all

Check kernel support for Category 1, 2, and 3 features.

--feature name

Check a specific feature. If name is list, a list of valid kernel feature names that can be checked will be printed.

page-server

Launches criu in page server mode.

--daemon

Runs page server as a daemon (background process).

--status-fd

Write \0 to the FD and close it once page-server is ready to handle requests. The status-fd allows to not daemonize a process and get its exit code at the end. It isn’t supposed to use --daemon and --status-fd together.

--address address

Page server IP address or hostname.

--port number

Page server port number.

--ps-socket fd

Use provided file descriptor as socket for incoming connection. In this case --address and --port are ignored. Useful for intercepting page-server traffic e.g. to add encryption or authentication.

--lazy-pages

Serve local memory dump to a remote lazy-pages daemon. In this mode the page-server reads local memory dump and allows the remote lazy-pages daemon to request memory pages in random order.

--tls-cacert file

Specifies the path to a trusted Certificate Authority (CA) certificate file to be used for verification of a client or server certificate. The file must be in PEM format. When this option is used only the specified CA is used for verification. Otherwise, the system’s trusted CAs and, if present, /etc/pki/CA/cacert.pem will be used.

--tls-cacrl file

Specifies a path to a Certificate Revocation List (CRL) file which contains a list of revoked certificates that should no longer be trusted. The file must be in PEM format. When this option is not specified, the file, if present, /etc/pki/CA/cacrl.pem will be used.

--tls-cert file

Specifies a path to a file that contains a X.509 certificate to present to the remote entity. The file must be in PEM format. When this option is not specified, the default location (/etc/pki/criu/cert.pem) will be used.

--tls-key file

Specifies a path to a file that contains TLS private key. The file must be in PEM format. When this option is not the default location (/etc/pki/criu/private/key.pem) will be used.

--tls

Use TLS to secure remote connections.

lazy-pages

Launches criu in lazy-pages daemon mode.

The lazy-pages daemon is responsible for managing user-level demand paging for the restored processes. It gets information required to fill the process memory pages from the restore and from the checkpoint directory. When a restored process access certain memory page for the first time, the lazy-pages daemon injects its contents into the process address space. The memory pages that are not yet requested by the restored processes are injected in the background.

exec

Executes a system call inside a destination task's context. This functionality is deprecated; please use Compel instead.

service

Launches criu in RPC daemon mode, where criu is listening for RPC commands over socket to perform. This is convenient for a case where daemon itself is running in a privileged (superuser) mode but clients are not.

dedup

Starts pagemap data deduplication procedure, where criu scans over all pagemap files and tries to minimize the number of pagemap entries by obtaining the references from a parent pagemap image.

cpuinfo dump

Fetches current CPU features and write them into an image file.

cpuinfo check

Fetches current CPU features (i.e. CPU the criu is running on) and test if they are compatible with the ones present in an image file.

CONFIGURATION FILES

Criu supports usage of configuration files to avoid the need of writing every option on command line, which is useful especially with repeated usage of same options. A specific configuration file can be passed with the "--config file" option. If no file is passed, the default configuration files /etc/criu/default.conf and $HOME/.criu/default.conf are parsed (if present on the system). If the environment variable CRIU_CONFIG_FILE is set, it will also be parsed.

The options passed to CRIU via CLI, RPC or configuration file are evaluated in the following order:

•apply_config(/etc/criu/default.conf)

•apply_config($HOME/.criu/default.conf)

•apply_config(CRIU_CONFIG_FILE)

•apply_config(--config file)

•apply_config(CLI) or apply_config(RPC)

•apply_config(RPC configuration file) (only for RPC mode)

Default configuration file parsing can be deactivated with "--no-default-config" if needed. Parsed configuration files are merged with command line options, which allows overriding boolean options.

Configuration file syntax

Comments are supported using '#' sign. The rest of the line is ignored. Options are the same as command line options without the '--' prefix, use one option per line (with corresponding argument if applicable, divided by whitespaces). If needed, the argument can be provided in double quotes (this should be needed only if the argument contains whitespaces). In case this type of argument contains a literal double quote as well, it can be escaped using the '\' sign. Usage of commands is disallowed and all other escape sequences are interpreted literally.

Example of configuration file to illustrate syntax:

```
$ cat ~/.criu/default.conf
tcp-established
work-dir "/home/USERNAME/criu/my \"work\" directory"
#this is a comment
no-restore-sibling   # this is another comment
```

Configuration files in RPC mode

Not only does criu evaluate configuration files in CLI mode, it also evaluates configuration files in RPC mode. Just as in CLI mode the configuration file values are evaluated first. This means that any option set via RPC will overwrite the configuration file setting. The user can thus change criu's default behavior but it is not possible to change settings which are explicitly set by the RPC client.

The RPC client can, however, specify an additional configuration file which will be evaluated after the RPC options (see above for option evaluation order). The RPC client can specify this additional configuration file via "req.opts.config_file = /path/to/file". The values from this configuration file will overwrite all other configuration file settings or RPC options. This can lead to undesired behavior of criu and should only be used carefully.

NON-ROOT

criu can be used as non-root with either the CAP_SYS_ADMIN capability or with the CAP_CHECKPOINT_RESTORE capability introduces in Linux kernel 5.9. CAP_CHECKPOINT_RESTORE is the minimum that is required.

criu also needs either CAP_SYS_PTRACE or a value of 0 in /proc/sys/kernel/yama/ptrace_scope (see ptrace(2)) to be able to interrupt the process for dumping.

Running criu as non-root has many limitations and depending on the process to checkpoint and restore it may not be possible.

In addition to CAP_CHECKPOINT_RESTORE it is possible to give criu additional capabilities to enable additional features in non-root mode.

Currently criu can benefit from the following additional capabilities:

•CAP_NET_ADMIN

•CAP_SYS_CHROOT

•CAP_SETUID

•CAP_SYS_RESOURCE

Note that for some operations, having a capability in a namespace other than the init namespace (i.e. the default/root namespace) is not sufficient. For example, in order to read symlinks in proc/[pid]/map_files CRIU requires CAP_CHECKPOINT_RESTORE in the init namespace; having CAP_CHECKPOINT_RESTORE while running in another user namespace (e.g. in a container) does not allow CRIU to read symlinks in /proc/[pid]/map_files.

Without access to /proc/[pid]/map_files checkpointing/restoring processes that have mapped deleted files may not be possible.

Independent of the capabilities it is always necessary to use "--unprivileged" to accept criu's limitation in non-root mode.

EXAMPLES

To checkpoint a program with pid of 1234 and write all image files into directory checkpoint:

```
    criu dump -D checkpoint -t 1234
```

To restore this program detaching criu itself:

```
    criu restore -d -D checkpoint
```

AUTHOR

The CRIU team.

COPYRIGHT

Copyright (C) 2011-2016, Parallels Holdings, Inc.


cryptmount

package: cryptmount

title: cryptmount(8)

text:
# cryptmount(8)

## NAME
cryptmount - mount/unmount/configure an encrypted filesystem

## SYNOPSIS
cryptmount TARGET [TARGET ...]

cryptmount --unmount TARGET [TARGET ...]

cryptmount --change-password TARGET

cryptmount --generate-key SIZE TARGET

cryptmount --swapon TARGET

cryptmount --swapoff TARGET

## DESCRIPTION
cryptmount allows an encrypted filesystem to be mounted or unmounted, without requiring superuser privileges, and assists the superuser in creating new encrypted filesystems. After initial configuration of the filesystem by the system administrator, the user needs only to provide the decryption password for that filing system in order for cryptmount to automatically configure device-mapper and loopback targets before mounting the filesystem.

cryptmount was written in response to differences between the newer device-mapper infrastructure of the linux-2.6 kernel series, and the older cryptoloop infrastructure which allowed ordinary users access to encrypted filesystems directly through mount (8).

## OPTIONS
-a --all

act on all available targets, e.g. for mounting all targets.

-m --mount

mount the specified target, configuring any required device-mapper or loopback devices. The user will be asked to supply a password to unlock the decryption key for the filesystem.

-u --unmount

unmount the specified target, and deconfigure any underlying device-mapper or loopback devices. No password is required, although the operation will fail if the filesystem is in use, or if a non-root user tries to unmount a filesystem mounted by a different user.

-S --status

provide information on whether the specified target is currently mounted or not

-l --list

lists all available targets, including basic information about the filesystem and mount point of each.

-c --change-password

change the password protecting the decryption key for a given filesystem.

-g --generate-key size

setup a decryption key for a new filesystem. size gives the length of the key in bytes.

-e --reuse-key existing-target

setup a decryption key for a new filesystem, using an existing key from another filesystem, for example to translate between different file-formats for storing a single key. This option is only available to the superuser.

-f --config-fd num

read configuration information about targets from file-descriptor num instead of the default configuration file. This option is only available to the superuser.

-w --passwd-fd num

read passwords from file-descriptor num instead of from the terminal, e.g. for using cryptmount within scripts or GUI wrappers. Each password is read once only, in contrast to terminal-based operation where new passwords would be requested twice for verification.

-p --prepare

prepare all the device-mapper and loopback devices needed to access a target, but do not mount. This is intended to allow the superuser to install a filesystem on an encrypted device.

-r --release

releases all device-mapper and loopback devices associated with a particular target. This option is only available to the superuser.

-s --swapon

enable the specified target for paging and swapping. This option is only available to the superuser.

-x --swapoff

disable the specified target for paging and swapping. This option is only available to the superuser.

-k --key-managers

list all the available formats for protecting the filesystem access keys.

-B --system-boot

setup all targets which have declared a "bootaction" parameter. This will typically be used to automatically mount encrypted filesystems, or setup encrypted swap partitions, on system startup. This option is only available to the superuser.

-Q --system-shutdown

close-down all targets which have declared a "bootaction" parameter. This is essentially the opposite of the "--system-boot" option.

-n --safetynet

attempts to close-down any mounted targets that should normally have been shutdown with --unmount or --swapoff. This option is only available to the superuser, and intended exclusively for use during shutdown/reboot of the operating system.

-v --version

show the version-number of the installed program.

## RETURN CODES
cryptmount returns zero on success. A non-zero value indicates a failure of some form, as follows:

1

unrecognized command-line option;

2

unrecognized filesystem target name;

3

failed to execute helper program;

100

insufficient privilege;

101

security failure in installation.

## EXAMPLE USAGE
In order to create a new encrypted filesystem managed by cryptmount, you can use the supplied 'cryptmount-setup' program, which can be used by the superuser to interactively configure a basic setup.

Alternatively, a manual setup allows more control of configuration settings. Before doing so, one should ensure that kernel support for /dev/loop and /dev/mapper is available, e.g. via

```
    modprobe -a loop dm-crypt
```

Now suppose that we wish to setup a new encrypted filesystem, that will have a target-name of "opaque". If we have a free disk partition available, say /dev/sdb63, then we can use this directly to store the encrypted filesystem. Alternatively, if we want to store the encrypted filesystem within an ordinary file, we need to create space using a recipe such as:

```
    dd if=/dev/zero of=/home/opaque.fs bs=1M count=512
```

and then replace all occurrences of '/dev/sdb63' in the following with '/home/opaque.fs'. (/dev/urandom can be used in place of /dev/zero, debatably for extra security, but is rather slower.)

First, we need to add an entry in /etc/cryptmount/cmtab, which describes the encryption that will be used to protect the filesystem itself and the access key, as follows:

```
    opaque {

        dev=/dev/sdb63 dir=/home/crypt

        fstype=ext2 mountoptions=defaults cipher=twofish

        keyfile=/etc/cryptmount/opaque.key

        keyformat=builtin

    }
```

Here, we will be using the "twofish" algorithm to encrypt the filesystem itself, with the built-in key-manager being used to protect the decryption key (to be stored in /etc/cryptmount/opaque.key).

In order to generate a secret decryption key (in /etc/cryptmount/opaque.key) that will be used to encrypt the filesystem itself, we can execute, as root:

```
    cryptmount --generate-key 32 opaque
```

This will generate a 32-byte (256-bit) key, which is known to be supported by the Twofish cipher algorithm, and store it in encrypted form after asking the system administrator for a password.

If we now execute, as root:

```
    cryptmount --prepare opaque
```

we will then be asked for the password that we used when setting up /etc/cryptmount/opaque.key, which will enable cryptmount to setup a device-mapper target (/dev/disk/by-id/dm-name-opaque). (If you receive an error message of the form device-mapper ioctl cmd 9 failed: Invalid argument , this may mean that you have chosen a key-size that isn't supported by your chosen cipher algorithm. You can get some information about suitable key-sizes by checking the output from "more /proc/crypto", and looking at the "min keysize" and "max keysize" fields.)

We can now use standard tools to create the actual filesystem on /dev/disk/by-id/dm-name-opaque:

```
    mke2fs /dev/disk/by-id/dm-name-opaque
```

(It may be advisable, after the filesystem is first mounted, to check that the permissions of the top-level directory created by mke2fs are appropriate for your needs.)

After executing

```
    cryptmount --release opaque

    mkdir /home/crypt
```

the encrypted filesystem is ready for use. Ordinary users can mount it by typing

```
    cryptmount -m opaque
```

or

```
    cryptmount opaque
```

and unmount it using

```
    cryptmount -u opaque
```

cryptmount keeps a record of which user mounted each filesystem in order to provide a locking mechanism to ensure that only the same user (or root) can unmount it.

## PASSWORD CHANGING
After a filesystem has been in use for a while, one may want to change the access password. For an example target called "opaque", this can be performed by executing:

```
    cryptmount --change-password opaque
```

After successfully supplying the old password, one can then choose a new password which will be used to re-encrypt the access key for the filesystem. (The filesystem itself is not altered or re-encrypted.)

## LUKS ENCRYPTED FILESYSTEMS
cryptmount can be used to provide easy access to encrypted filesystems compatible with the Linux Unified Key Setup (LUKS) capabilities of the cryptsetup application.

In order to access an existing LUKS partition, an entry needs to be created within /etc/cryptmount/cmtab. For example, if the hard-disk partition /dev/sdb62 is used to contain a LUKS encrypted ext3 filesystem, an entry of the form:

```
    LUKS {

        keyformat=luks

        dev=/dev/sdb62          keyfile=/dev/sdb62

        dir=/home/luks-dir      fstype=ext3

    }
```

would allow this to be mounted via cryptmount beneath /home/luks-dir by executing

```
    cryptmount LUKS
```

cryptmount will also allow any user that knows one of the access-passwords to change their password via

```
    cryptmount --change-password LUKS
```

cryptmount also provides basic support for creating new LUKS encrypted filesystems, which can be placed within ordinary files as well as disk partitions, via the '--generate-key' recipe shown above. However, to exploit the full range of functionality within LUKS, such as for adding multiple passwords, one needs to use cryptsetup

It is strongly recommended that you do not attempt to use LUKS support in combination with cryptmount's features for storing multiple encrypted filesystems within a single disk partition or an ordinary file. This is because of assumptions within the cryptsetup-luks design that the LUKS key-material is always stored at the beginning of the disk partition.

## FILES
/etc/cryptmount/cmtab - main configuration file

/run/cryptmount.status - record of mounted filesystems

## SEE ALSO
cmtab(5), cryptmount-setup(8), cryptsetup(8), mount(8)

## BUGS
The author would be grateful for any constructive suggestions and bug-reports, via https://github.com/rwpenney/cryptmount/issues

## COPYRIGHT NOTICE
cryptmount is (C)Copyright 2005-2026, RW Penney

and is supplied with NO WARRANTY. Licencing terms are as described in the file "COPYING" within the cryptmount source distribution.

branch: sisyphus


cryptmount-setup

title: cryptmount-setup(8)

summary: setup a new encrypted filesystem

text:
# cryptmount-setup(8)

## NAME
cryptmount-setup - setup a new encrypted filesystem

## SYNOPSIS
cryptmount-setup

## DESCRIPTION
cryptmount-setup assists in the initial configuration of an encrypted filesystem, to be managed by cryptmount (8).

If run by the superuser, cryptmount-setup will allow a basic LUKS-encrypted filesystem to be created within an ordinary file. The size, location, mount-point and ownership of the filesystem can be selected interactively. For more advanced options, please see the manual page for cryptmount (8) or cmtab (5)

## SEE ALSO
cmtab(5) cryptmount(8)

## COPYRIGHT NOTICE
cryptmount is (C)Copyright 2005-2026, RW Penney

and is supplied with NO WARRANTY. Licencing terms are as described in the file "COPYING" within the cryptmount source distribution.


cryptsetup

package: cryptsetup

title: cryptsetup(8)

text:
# cryptsetup(8)

## NAME
cryptsetup - utility for configuring and managing encrypted storage devices

## SYNOPSIS
cryptsetup <action> [<options>] <action args>

## DESCRIPTION
Cryptsetup is a utility for configuring and managing full-disk encryption on storage devices. It can encrypt block devices (such as hard drives or partitions) and containers (disk images stored as files).

When you unlock an encrypted volume, cryptsetup creates a new device mapping that applications can access like any regular storage device. The actual encryption and decryption work is performed transparently by the kernel’s device-mapper dm-crypt driver.

Cryptsetup works with two main volume types: plain encrypted volumes and LUKS (Linux Unified Key Setup) volumes. Plain volumes provide basic encryption, while LUKS volumes include a metadata header that enables advanced features like multiple keyslots and key management. Additionally, LUKS can be used to manage hardware-based encryption on OPAL-capable storage drives.

Cryptsetup also provides limited support for volumes created by other encryption systems, including loop-AES, TrueCrypt, VeraCrypt, BitLocker, and FileVault2.

For more information about a specific cryptsetup action, see cryptsetup-<action>(8), where <action> is the name of the cryptsetup action.

Cryptsetup devices can be activated during boot through crypttab(5), which is part of systemd(1) or other system init scripts.

## BASIC ACTIONS
The following are valid actions for all supported device types.

### OPEN
open <device> <name> --type <device_type>

Opens (creates a mapping with) <name> backed by device <device>. See cryptsetup-open(8).

### CLOSE
close <name>

Removes the existing mapping <name> and wipes the key from kernel memory. See cryptsetup-close(8).

### STATUS
status <name>

Reports the status for the mapping <name>. See cryptsetup-status(8).

### RESIZE
resize <name>

Resizes an active mapping <name>. See cryptsetup-resize(8).

### REFRESH
refresh <name>

Refreshes parameters of active mapping <name>. See cryptsetup-refresh(8).

### REENCRYPT
reencrypt <device> or --active-name <name> [<new_name>]

Run LUKS device reencryption. See cryptsetup-reencrypt(8).

## PLAIN MODE
Plain dm-crypt encrypts the device sector-by-sector with a single, non-salted hash of the passphrase. No checks are performed, and no metadata is used. There is no formatting operation. When the raw device is mapped (opened), the usual device operations can be used on the mapped device, including filesystem creation. Mapped devices usually reside in /dev/mapper/<name>.

The following are valid plain device type actions:

### OPEN
open --type plain <device> <name>

create <name> <device> (OBSOLETE syntax)

Opens (creates a mapping with) <name> backed by device <device>. See cryptsetup-open(8).

## LUKS EXTENSION
LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It adds a standardized header at the start of the device, a keyslot area directly behind the header and the bulk data area behind that. The whole set is called a 'LUKS container'. The device that a LUKS container resides on is called a 'LUKS device'. For most purposes, both terms can be used interchangeably.

LUKS can manage multiple passphrases that can be individually revoked or changed. Each passphrase uses an individual keyslot containing a volume key for data encryption. Keyslots can be securely scrubbed from persistent media due to the use of anti-forensic stripes. Passphrases are protected against brute-force attacks by the Password-Based Key Derivation Function (PBKDF). A passphrase stored in a file is called a key file. The only difference between a passphrase and a key file is that a key file can contain binary data. Both are processed the same.

LUKS version 1 (or LUKS1) is the original metadata format, while LUKS2 is a new version that allows additional extensions like different PBKDF algorithms or authenticated encryption. You can format the device with a specific LUKS version with --type luks1 or --type luks2 in the luksFormat command. Normally, you do not need to specify any version as it is recognized automatically. The default format is LUKS2.

The <device> parameter can also be specified by a LUKS UUID in the format UUID=<uuid>.

The LUKS header can be detached from data (stored separately). To specify a detached header, the --header parameter can be used in all LUKS commands and always takes precedence over the positional <device> parameter.

The following are valid LUKS actions:

### FORMAT
luksFormat <device> [<key file>]

Initializes a LUKS partition and sets the initial passphrase (for keyslot 0). See cryptsetup-luksFormat(8).

### OPEN
open --type luks <device> <name>

luksOpen <device> <name> (old syntax)

Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the supplied passphrase. See cryptsetup-open(8).

### SUSPEND
luksSuspend <name>

Suspends an active device (all IO operations will block and accesses to the device will wait indefinitely) and wipes the encryption key from kernel memory. See cryptsetup-luksSuspend(8).

### RESUME
luksResume <name>

Resumes a suspended device and reinstates the encryption key. See cryptsetup-luksResume(8).

### ADD KEY
luksAddKey <device> [<key file with new key>]

Adds a new passphrase using an existing passphrase. See cryptsetup-luksAddKey(8).

### REMOVE KEY
luksRemoveKey <device> [<key file with passphrase to be removed>]

Removes the supplied passphrase from the LUKS device. See cryptsetup-luksRemoveKey(8).

### CHANGE KEY
luksChangeKey <device> [<new key file>]

Changes an existing passphrase. See cryptsetup-luksChangeKey(8).

### CONVERT KEY
luksConvertKey <device>

Converts an existing LUKS2 keyslot to new PBKDF parameters. See cryptsetup-luksConvertKey(8).

### KILL SLOT
luksKillSlot <device> <number>

Wipe the keyslot with the <number> from the LUKS device. See cryptsetup-luksKillSlot(8).

### ERASE
erase <device>

luksErase <device> (old syntax)

Erase all keyslots and make the LUKS container permanently inaccessible. See cryptsetup-erase(8).

### UUID
luksUUID <device>

Print or set the UUID of a LUKS device. See cryptsetup-luksUUID(8).

### IS LUKS
isLuks <device>

Returns true, if <device> is a LUKS device, false otherwise. See cryptsetup-isLuks(8).

### DUMP
luksDump <device>

Dump the header information of a LUKS device. See cryptsetup-luksDump(8).

### HEADER BACKUP
luksHeaderBackup <device> --header-backup-file <file>

Stores a binary backup of the LUKS header and keyslot area. See cryptsetup-luksHeaderBackup(8).

### HEADER RESTORE
luksHeaderRestore <device> --header-backup-file <file>

Restores a binary backup of the LUKS header and keyslot area from the specified file. See cryptsetup-luksHeaderRestore(8).

### TOKEN
token <add|remove|import|export> <device>

Manipulate token objects used for obtaining passphrases. See cryptsetup-token(8).

### CONVERT
convert <device> --type <format>

Converts the device between LUKS1 and LUKS2 format (if possible). See cryptsetup-convert(8).

### CONFIG
config <device>

Set permanent configuration options (store to LUKS header). See cryptsetup-config(8).

## LOOP-AES EXTENSION
Cryptsetup supports mapping a loop-AES encrypted partition using a compatibility mode.

### OPEN
open --type loopaes <device> <name> --key-file <keyfile>

loopaesOpen <device> <name> --key-file <keyfile> (old syntax)

Opens the loop-AES <device> and sets up a mapping <name>. See cryptsetup-open(8).

See also section 7 of the FAQ and loop-AES <http://loop-aes.sourceforge.net> for more information regarding loop-AES.

## TCRYPT (TRUECRYPT AND VERACRYPT COMPATIBLE) EXTENSION
Cryptsetup supports mapping of TrueCrypt, tcplay, or VeraCrypt encrypted partitions using a native Linux kernel API. Header formatting and TCRYPT header change are not supported; cryptsetup never changes the TCRYPT header on-device.

TCRYPT extension requires the kernel userspace crypto API to be available. If you are configuring the kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).

Because the TCRYPT header is encrypted, you must always provide a valid passphrase and keyfiles.

Cryptsetup should recognize all header variants, except legacy cipher chains using LRW encryption mode with a 64-bit encryption block (namely, Blowfish in LRW mode is not recognized; this is a limitation of the kernel crypto API).

VeraCrypt is an extension of TrueCrypt with an increased iteration count, so unlocking can take quite a lot of time.

To open a VeraCrypt device with a custom Personal Iteration Multiplier (PIM) value, use either the --veracrypt-pim PIM option to directly specify the PIM on the command line or use --veracrypt-query-pim to be prompted for the PIM.

The PIM value affects the number of iterations applied during key derivation. Please refer to PIM <https://veracrypt.io/en/Personal%20Iterations%20Multiplier%20(PIM).html> for more detailed information.

If you need to disable VeraCrypt device support, use --disable-veracrypt option.

Activation with tcryptOpen is supported only for cipher chains using LRW or XTS encryption modes.

The tcryptDump command should work for all recognized TCRYPT devices and doesn’t require superuser privilege.

To map the system device (device with boot loader where the whole encrypted system resides), use --tcrypt-system option. Please read specific info in cryptsetup-tcryptOpen(8) --tcrypt-system option section as mapping system-encrypted device is tricky.

To use a hidden header (and map hidden device, if available), use --tcrypt-hidden option.

To explicitly use the backup (secondary) header, use --tcrypt-backup option.

There is no protection for a hidden volume if the outer volume is mounted. The reason is that if there were any protection, it would require some metadata describing what to protect in the outer volume, and the hidden volume would become detectable.

### OPEN
open --type tcrypt <device> <name>

tcryptOpen_ <device> <name> (old syntax)

Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping <name>. See cryptsetup-open(8).

### DUMP
tcryptDump <device>

Dump the header information of a TCRYPT device. See cryptsetup-tcryptDump(8).

See also TrueCrypt <https://en.wikipedia.org/wiki/TrueCrypt> and VeraCrypt <https://en.wikipedia.org/wiki/VeraCrypt> pages for more information.

Please note that cryptsetup does not use TrueCrypt or VeraCrypt code; please report all problems related to this compatibility extension to the cryptsetup project.

## BITLK (WINDOWS BITLOCKER COMPATIBLE) EXTENSION
Cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted partitions using a native Linux kernel API. Header formatting and BITLK header changes are not supported; cryptsetup never changes the BITLK header on-device.

BITLK extension requires the kernel userspace crypto API to be available (for details, see the TCRYPT section).

Cryptsetup should recognize all BITLK header variants, except the legacy header used in Windows Vista systems and partially decrypted BitLocker devices. Activation of legacy devices encrypted in CBC mode requires at least a Linux kernel version 5.3, and for devices using the Elephant diffuser, kernel 5.6.

The bitlkDump command should work for all recognized BITLK devices and doesn’t require superuser privilege.

For unlocking with the open, a password, a recovery passphrase, or a startup key must be provided.

Additionally, unlocking using the volume key is supported. You must provide BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file option. The key must be decrypted and without the header (only 128/256/512 bits of key data depending on the used cipher and mode).

Other unlocking methods (TPM, SmartCard) are not supported.

### OPEN
open --type bitlk <device> <name>

bitlkOpen <device> <name> (old syntax)

Opens the BITLK (a BitLocker-compatible) <device> and sets up a mapping <name>. See cryptsetup-open(8).

### DUMP
bitlkDump <device>

Dump the header information of a BITLK device. See cryptsetup-bitlkDump(8).

Please note that cryptsetup does not use any Windows BitLocker code; please report all problems related to this compatibility extension to the cryptsetup project.

## FVAULT2 (APPLE MACOS FILEVAULT2 COMPATIBLE) EXTENSION
Cryptsetup supports the mapping of FileVault2 (FileVault2 full-disk encryption) by Apple for the macOS operating system using a native Linux kernel API.

Cryptsetup supports only FileVault2 based on Core Storage and HFS+ filesystem (introduced in MacOS X 10.7 Lion). It does NOT support the new version of FileVault based on the APFS filesystem used in recent macOS versions.

Header formatting and FVAULT2 header changes are not supported; cryptsetup never changes the FVAULT2 header on-device.

FVAULT2 extension requires the kernel userspace crypto API to be available (for details, see the TCRYPT section) and a kernel driver for the HFS+ (hfsplus) filesystem.

Cryptsetup should recognize the basic configuration for portable drives.

The fvault2Dump command should work for all recognized FVAULT2 devices and doesn’t require superuser privilege.

For unlocking with the open, a password must be provided. Other unlocking methods are not supported.

### OPEN
open --type fvault2 <device> <name>

fvault2Open <device> <name> (old syntax)

Opens the FVAULT2 (a FileVault2-compatible) <device> (usually the second partition on the device) and sets up a mapping <name>. See cryptsetup-open(8).

## SED (SELF ENCRYPTING DRIVE) OPAL EXTENSION
Cryptsetup supports using native hardware encryption on drives that provide an OPAL interface, both nested with dm-crypt and standalone. Passphrases, tokens and metadata are stored using the LUKS2 header format, and are thus compatible with any software or system that uses LUKS2 (e.g., tokens).

OPAL support requires at least kernel v6.4. Resizing devices is not supported.

The --hw-opal can be specified for OPAL + dm-crypt, and --hw-opal-only can be specified to use OPAL only, without a dm-crypt layer.

Opening, closing and enrolling tokens work the same way as with LUKS2 and dm-crypt. The new parameters are only necessary when formatting; the LUKS2 metadata will ensure the right setup is performed when opening or closing.

If no subsystem label is specified, it will be automatically set to HW-OPAL so that it is immediately apparent when a device uses OPAL.

### FORMAT
luksFormat --type luks2 --hw-opal <device> [<key file>]

Additionally specify --hw-opal-only instead of --hw-opal to avoid the dm-crypt layer. Other than the usual passphrase, an admin password will have to be specified when formatting the drive’s first partition, and will have to be re-supplied when formatting any other partition until a factory reset is performed.

### ERASE
erase <device>

Securely erase a partition or device. Requires admin password. Additionally specify --hw-opal-factory-reset for a FULL factory reset of the drive, using the drive’s PSID (typically printed on the label) instead of the admin password.

PSID must be entered without dashes, spaces or underscores.

WARNING: A factory reset will cause ALL data on the device to be lost, regardless of the partition it is run on, if any, and regardless of any LUKS2 header backup.

## MISCELLANEOUS ACTIONS

### REPAIR
repair <device>

Tries to repair the device metadata if possible. Currently supported only for LUKS device type. See cryptsetup-repair(8).

### BENCHMARK
benchmark <options>

Benchmarks, ciphers and KDF (key derivation function). See cryptsetup-benchmark(8).

## PLAIN MODE OR LUKS?
Unless you understand the cryptographic background well, use LUKS. With plain mode, there are a number of possible user errors that massively decrease security. While LUKS cannot fix them all, it can lessen the impact for many of them.

## WARNINGS
A lot of good information on the risks of using encrypted storage, on handling problems and on security aspects can be found in the Cryptsetup FAQ. Read it. Nonetheless, some risks deserve to be mentioned here.

Backup: Storage media die. Encryption has no influence on that. Backup is mandatory for encrypted data as well, if the data has any worth. See the Cryptsetup FAQ for advice on how to back up an encrypted volume.

Character encoding: If you enter a passphrase with special symbols, the passphrase can change depending on character encoding. Keyboard settings can also be changed, which can make blind input hard or impossible. For example, switching from some ASCII 8-bit variant to UTF-8 can lead to a different binary encoding and hence a different passphrase seen by cryptsetup, even if what you see on the terminal is exactly the same. It is therefore highly recommended to select passphrase characters only from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all ASCII variants and UTF-8.

LUKS header: If the header of a LUKS volume gets damaged, all data is permanently lost unless you have a header backup. If a keyslot is damaged, it can only be restored from a header backup or if another active keyslot with a known passphrase is undamaged. This risk is the result of a trade-off between security and safety, as LUKS is designed for fast and secure wiping by just overwriting the header and keyslot area.

Previously used partitions: If a partition was previously used, it is a very good idea to wipe filesystem signatures, data, etc., before creating a LUKS or plain dm-crypt container. For a quick removal of filesystem signatures, use wipefs(8) with the --all option. Note that it does not remove data; it only invalidates known format signatures. For a full wipe, overwrite the whole partition before creating a container. If you do not know how to do that, the cryptsetup FAQ describes several options.

## EXAMPLES
Example 1: Create LUKS 2 container on block device /dev/sdX.

sudo cryptsetup --type luks2 luksFormat /dev/sdX

Example 2: Add an additional passphrase to keyslot 5.

sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX

Example 3: Create LUKS header backup and save it to a file.

sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile

Example 4: Open LUKS container on /dev/sdX and map it to sdX_crypt.

sudo cryptsetup open /dev/sdX sdX_crypt

WARNING: The command in example 5 will erase all keyslots.

You cannot use your LUKS container afterward anymore unless you have a backup to restore.

Example 5: Erase all keyslots on /dev/sdX.

sudo cryptsetup erase /dev/sdX

Example 6: Restore LUKS header from backup file.

sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile

## RETURN CODES
Cryptsetup returns 0 on success and a non-zero value on error.

Error codes are: 1 wrong parameters, 2 no permission (bad passphrase), 3 out of memory, 4 wrong device specified, 5 device already exists or device is busy.

## NOTES

### Passphrase processing for PLAIN mode
Note that no iterated hashing or salting is done in plain mode. If hashing is done, it is a single direct hash. This means that low-entropy passphrases are easy to attack in plain mode.

From a terminal: The passphrase is read until the first newline, i.e., '\n'. The input without the newline character is processed with the default hash or the hash specified with --hash. The hash result will be truncated to the key size of the used cipher, or the size specified with -s.

From stdin: Reading will continue until a newline (or until the maximum input size is reached), with the trailing newline stripped. The maximum input size is defined by the same compiled-in default as the maximum key file size and can be overwritten using the --keyfile-size option.

The data read will be hashed with the default hash or the hash specified with --hash. The hash result will be truncated to the key size of the used cipher, or the size specified with -s.

Note that if --key-file=- is used for reading the key from stdin, trailing newlines are not stripped from the input.

If "plain" is used as an argument to --hash, the input data will not be hashed. Instead, it will be zero-padded (if shorter than the key size) or truncated (if longer than the key size) and used directly as the binary key. This is useful for directly specifying a binary key. No warning will be given if the amount of data read from stdin is less than the key size.

From a key file: It will be truncated to the key size of the used cipher or the size given by -s and directly used as a binary key.

The --hash argument is being ignored. The --hash option is usable only for stdin input in plain mode.

If the key file is shorter than the key, cryptsetup will quit with an error. The maximum input size is defined by the same compiled-in default as the maximum key file size and can be overwritten using the --keyfile-size option.

### Passphrase processing for LUKS
From a terminal: The passphrase is read until the first newline and then processed by PBKDF2 without the newline character.

From stdin: LUKS will read passphrases from stdin up to the first newline character or the compiled-in maximum key file length. If --keyfile-size is given, it is ignored.

From key file: The complete keyfile is read up to the compiled-in maximum size. Newline characters do not terminate the input. The --keyfile-size option can be used to limit what is read.

LUKS uses Password-Based Key Derivation Function (PBKDF) to protect against brute-force attacks and to give some protection to low-entropy passphrases (see cryptsetup FAQ). LUKS1 supports the PBKDF2 algorithm only, while LUKS2 also supports memory-hard Argon2. PBKDFs are configured with costs: how long the iteration should run (CPU cost or iteration count), how much memory is used (memory cost), and how many parallel processes are used (parallel cost). PBKDF2 supports only iteration count. Cryptsetup uses PBKDF benchmarking to calculate optimal costs based on the computer where the new passphrase is being initialized. If needed, these costs can also be overwritten. Note that there are some hardcoded limits, for details see MINIMAL AND MAXIMAL PBKDF COSTS section in --pbkdf option description.

Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat), the user may specify how much time the passphrase processing should consume. The time is used to determine the iteration count for PBKDF2, and higher times will offer better protection for low-entropy passphrases, but the open command will take longer to complete. For passphrases that have entropy higher than the used key length, higher iteration times will not increase security.

The default setting of one or two seconds is sufficient for most practical cases. The only exception is a low-entropy passphrase used on a device with a slow CPU, as this will result in a low iteration count. On a slow device, it may be advisable to increase the iteration time using the --iter-time option to obtain a higher iteration count. This does slow down all later luksOpen operations accordingly.

### Incoherent behavior for invalid passphrases/keys
LUKS checks for a valid passphrase when a keyslot is decrypted.

The behavior of plain dm-crypt is different. It will always unlock the device with the passphrase given. If the given passphrase is wrong, the device mapped by plain dm-crypt will use the wrong encryption key, and the data will be unreadable.

### Supported ciphers, modes, hashes and key sizes
The available combinations of ciphers, modes, hashes and key sizes depend on kernel support. See /proc/crypto for a list of available options. You might need to load additional kernel crypto modules to get more options.

Cryptsetup processes many operations outside of the kernel, so the configured cryptographic library must also support selected algorithms. Some algorithms may be missing as cryptsetup can be compiled with various cryptographic backends (libraries).

### Notes on passphrases
Mathematics can’t be bribed. Make sure you keep your passphrases safe. There are a few nice tricks for constructing a fallback when suddenly, out of the blue, your brain refuses to cooperate. These fallbacks need LUKS, as it’s only possible with LUKS to have multiple passphrases. Still, if your attacker model does not prevent it, storing your passphrase in a sealed envelope somewhere may be a good idea as well.

### Notes on Random Number Generators
Random Number Generators (RNGs) used in cryptsetup are always the kernel RNGs without any modifications or additions to the data stream produced.

There are two types of randomness that cryptsetup/LUKS needs. One type is used for salts, the AF splitter and for wiping deleted keyslots. The second type is used for the volume key.

With recent kernels (Linux kernel 5.6), you do not need to worry about selecting RNG (/dev/random or /dev/urandom). In a low-entropy situation (embedded system), initialization of the kernel RNG can take a very long time, but this happens before cryptsetup can even be started. Use cryptsetup --help to show the compiled-in default random number generator. See urandom(4) for more information.

### Authenticated disk encryption (EXPERIMENTAL)
Normal disk encryption modes are length-preserving (the plaintext sector is the same size as a ciphertext sector) and can provide only confidentiality protection, not cryptographically sound data integrity protection.

Authenticated modes require additional space per-sector for the authentication tag and use Authenticated Encryption with Additional Data (AEAD) algorithms.

If you configure a LUKS2 device with data integrity protection, there will be an underlying dm-integrity device, which provides additional per-sector metadata space and data journal protection to ensure atomicity of data and metadata updates. Because there must be additional space for metadata and journal, the available space for the device will be smaller than for length-preserving modes.

The dm-crypt device then resides on top of such a dm-integrity device. All activation and deactivation of this device stack is performed by cryptsetup; there is no difference in using luksOpen for integrity-protected devices. If you want to format a LUKS2 device with data integrity protection, use --integrity option (see cryptsetup-luksFormat(8)).

Albeit Linux kernel 5.7 added TRIM support for standalone dm-integrity devices, cryptsetup(8) can’t offer support for discards (TRIM) in authenticated encryption mode, because the underlying dm-crypt kernel module does not support this functionality when dm-integrity is used as auth tag space allocator (see --allow-discards in cryptsetup-open(8)).

Some integrity modes require two independent keys (a key for encryption and authentication). Both these keys are stored in one LUKS keyslot.

Support for authenticated modes is experimental, and only some modes are available now. Note that very few authenticated encryption algorithms are suitable for disk encryption. You also cannot use CRC32 or other non-cryptographic checksums (other than the special integrity mode "none"). If, for some reason, you want to have integrity control without using authentication mode, then you should separately configure dm-integrity independently of LUKS2.

### Notes on loopback device use
Cryptsetup is usually used directly on a block device (disk partition or LVM volume). However, if the device argument is a file, cryptsetup tries to allocate a loopback device and map it into this file. Of course, you can always map a file to a loop device manually. See the cryptsetup FAQ for an example.

When device mapping is active, you can see the loop backing file in the status command output. Also see losetup(8).

### LUKS2 header locking
The LUKS2 on-disk metadata is updated in several steps, and to achieve a proper atomic update, there is a locking mechanism. For an image in a file, the code uses the flock(2) system call. For a block device, lock is performed over a special file stored in a locking directory (by default /run/cryptsetup). The locking directory should be created with the proper security context by the distribution during the boot-up phase. Only LUKS2 uses locks; other formats do not use this mechanism.

### LUKS on-disk format specification
For LUKS on-disk metadata specification, see LUKS1 <https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification> and LUKS2 <https://gitlab.com/cryptsetup/LUKS2-docs>.

## AUTHORS
Cryptsetup was originally written by Jana Saout <jana@saout.de>. The LUKS extensions and original man page were written by Clemens Fruhwirth <clemens@endorphin.org>. Man page extensions by Milan Broz <gmazyland@gmail.com>. Man page rewrite and extension by Arno Wagner <arno@wagner.name>.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-benchmark

title: cryptsetup-benchmark(8)

summary: benchmarks ciphers and KDF

text:
# cryptsetup-benchmark(8)

## NAME
cryptsetup-benchmark - benchmarks ciphers and KDF

## SYNOPSIS
cryptsetup benchmark [<options>]

## DESCRIPTION
Benchmarks, ciphers and KDF (key derivation function). Without parameters, it tries to measure a few common configurations.

To benchmark other ciphers or modes, specify --cipher and --key-size options.

To benchmark PBKDF you need to specify --pbkdf or --hash with optional cost parameters --iter-time, --pbkdf-memory or --pbkdf-parallel.

This benchmark uses memory only and is only informative. You cannot directly predict real storage encryption speed from it.

For testing block ciphers, this benchmark requires the kernel userspace crypto API to be available. If you are configuring the kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).

<options> can be [--cipher, --key-size, --hash, --pbkdf, --iter-time, --pbkdf-memory, --pbkdf-parallel].

## OPTIONS
--batch-mode, -q

Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

--cipher, -c <cipher-spec>

Set the cipher specification string.

--debug or --debug-json

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. If --debug-json is used, additional LUKS2 JSON data structures are printed.

--hash, -h <hash-spec>

The specified hash is used for PBKDF2 and the AF splitter.

--help, -?

Show help text and default parameters.

--iter-time, -i <number of milliseconds>

The number of milliseconds to spend with PBKDF passphrase processing. Specifying 0 as a parameter selects the compiled-in default.

--key-size, -s bits

Sets key size in bits. The argument has to be a multiple of 8. The possible key sizes are limited by the cipher and mode used. See /proc/crypto for more information. Note that the key size in /proc/crypto is stated in bytes.

This option can be used for open --type plain or luksFormat. All other LUKS actions will use the key size specified in the LUKS header. Use cryptsetup --help to show the compiled-in defaults.

--pbkdf <PBKDF spec>

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2 <https://www.cryptolux.org/index.php/Argon2> for more info). For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF for LUKS2 is set during compilation time and is available in the cryptsetup --help output.

A PBKDF is used for increasing the dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, memory and parallel cost.

For PBKDF2, only the time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required during the process of key derivation) and parallel cost (number of threads that run in parallel during the key derivation.

Note that increasing memory cost also increases time, so the final parameter values are measured by a benchmark. The benchmark tries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost is decreased as well. The parallel cost --pbkdf-parallel is constant and is checked against available CPU cores.

You can see all PBKDF parameters for a particular LUKS2 keyslot with the cryptsetup-luksDump(8) command.

If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time or cause out-of-memory conditions with unconditional process termination. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.

MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration count is 1000 and the maximum is 4294967295 (maximum for 32-bit unsigned integer). Memory and parallel costs are not supported for PBKDF2. For Argon2i and Argon2id, the minimum iteration count (CPU cost) is 4, and the maximum is 4294967295 (maximum for a 32-bit unsigned integer). Minimum memory cost is 32 KiB and maximum is 4 GiB. If the memory cost parameter is benchmarked (not specified by a parameter), it is always in the range from 64 MiB to 1 GiB. Memory cost above 1GiB (up to the 4GiB maximum) can be setup only by the --pbkdf-memory parameter. The parallel cost minimum is 1 and maximum 4 (if enough CPU cores are available, otherwise it is decreased by the available CPU cores).

WARNING: Increasing PBKDF computational costs above the mentioned limits provides negligible additional security improvement. While elevated costs significantly increase brute-force overhead, they offer negligible protection against dictionary attacks. The marginal cost increase for processing an entire dictionary remains fundamentally insufficient.

The hardcoded PBKDF limits represent engineered trade-offs between cryptographic security and operational usability. LUKS maintains portability and must be used within a reasonable time on resource-constrained systems.

Cryptsetup deliberately restricts maximum memory cost (4 GiB) and parallel cost (4) parameters due to architectural limitations (like embedded and legacy systems).

PBKDF memory cost mandates actual physical RAM allocation with intensive write operations that must remain in physical RAM. Any swap usage results in unacceptable performance degradation. Memory management often overcommits allocations beyond available physical memory, expecting most allocated memory to remain unused. In such situations, as PBKDF always uses all allocated memory, it frequently causes out-of-memory failures that abort cryptsetup operations.

--pbkdf-memory number

Set the memory cost for PBKDF (for Argon2i/id, the number represents kilobytes). Note that it is the maximal value; PBKDF benchmark or available physical memory can decrease it. This option is not available for PBKDF2.

--pbkdf-parallel number

Set the parallel cost for PBKDF (number of threads, up to 4). Note that it is the maximal value; it is decreased automatically if the CPU online count is lower. This option is not available for PBKDF2.

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-bitlkDump

title: cryptsetup-bitlkDump(8)

text:
# cryptsetup-bitlkDump(8)

## NAME
cryptsetup-bitlkDump - dump the header information of a BITLK (BitLocker compatible) device

## SYNOPSIS
cryptsetup bitlkDump [<options>] <device>

## DESCRIPTION
Dump the header information of a BITLK (BitLocker compatible) device.

If the --dump-volume-key option is used, the BITLK device volume key is dumped instead of header information. You have to provide a password or keyfile to dump the volume key.

Beware that the volume key can be used to decrypt the data stored in the container without a passphrase. This means that if the volume key is compromised, the whole device has to be erased to prevent further access. Use this option carefully.

<options> can be [--dump-volume-key, --volume-key-file, --key-file, --keyfile-offset, --keyfile-size, --timeout].

## OPTIONS
--batch-mode, -q

Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

--debug or --debug-json

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. If --debug-json is used, additional LUKS2 JSON data structures are printed.

--dump-volume-key, --dump-master-key (OBSOLETE alias)

Print the volume key in the displayed information. Use with care, as the volume key can be used to bypass the passphrases, see also option --volume-key-file.

--help, -?

Show help text and default parameters.

--key-file, -d file

Read the passphrase from the file. If the name given is "-", then the passphrase will be read from stdin. In this case, reading will not stop at newline characters.

See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for more information.

--keyfile-offset value

Skip value bytes at the beginning of the key file.

--keyfile-size, -l value

Read a maximum of value bytes from the key file. The default is to read the whole file up to the compiled-in maximum that can be queried with --help. Supplying more data than the compiled-in maximum aborts the operation. This option is useful to cut trailing newlines, for example. If --keyfile-offset is also given, the size count starts after the offset.

--timeout, -t seconds

The number of seconds to wait before a timeout on passphrase input via terminal. It is relevant every time a passphrase is asked. It has no effect if used in conjunction with --key-file. This option is useful when the system should not stall if the user does not input a passphrase, e.g., during boot. The default is a value of 0 seconds, which means to wait forever.

--usage

Show short option help.

--version, -V

Show the program version.

--volume-key-file file, --master-key-file file (OBSOLETE alias)

Use a volume key stored in a file. The volume key is stored in a file instead of being printed out to standard output.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-close

title: cryptsetup-close(8)

text:
# cryptsetup-close(8)

## NAME
cryptsetup-close - removes the existing mapping <name> (and the associated key)

## SYNOPSIS
cryptsetup close [<options>] <name>

## DESCRIPTION
Removes the existing mapping <name> and wipes the key from kernel memory.

For backward compatibility, there are close command aliases: remove, plainClose, luksClose, loopaesClose, tcryptClose, bitlkClose (all behave the same, device type is determined automatically from the active device).

<options> can be [--deferred, --cancel-deferred, --header, --disable-locks].

## OPTIONS
--batch-mode, -q

Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

--cancel-deferred

Removes a previously configured deferred device removal in the close command.

--debug or --debug-json

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. If --debug-json is used, additional LUKS2 JSON data structures are printed.

--deferred

Defers device removal in the close command until the last user closes it.

--disable-locks

Disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats. WARNING: Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used).

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-config

title: cryptsetup-config(8)

text:
# cryptsetup-config(8)

## NAME
cryptsetup-config - set permanent configuration options (store to LUKS header)

## SYNOPSIS
cryptsetup config <options> <device>

## DESCRIPTION
Set permanent configuration options (store to LUKS header). The config command is supported only for LUKS2.

The permanent options can be --priority to set priority (normal, prefer, ignore) for keyslot (specified by --key-slot) or --label and --subsystem.

<options> can be [--priority, --label, --subsystem, --key-slot, --header, --disable-locks].

## OPTIONS
--batch-mode, -q

Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

--debug or --debug-json

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. If --debug-json is used, additional LUKS2 JSON data structures are printed.

--disable-locks

Disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats. WARNING: Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used).

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. The maximum number of keyslots depends on the LUKS version. LUKS1 can have up to 8 keyslots. LUKS2 can have up to 32 keyslots based on keyslot area size and key size, but a valid keyslot ID can always be between 0 and 31 for LUKS2.

--label <label>, --subsystem <subsystem>

Set label and subsystem description for LUKS2 device. These are similar to filesystem labels. The label and subsystem are optional fields and can be later used in udev scripts to trigger user actions once the device marked by these labels is detected.

--priority <normal|prefer|ignore>

Set a priority for LUKS2 keyslot. The prefer priority marked slots are tried before the normal priority. The ignored priority means that the slot is never used, if not explicitly requested by --key-slot option.

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-convert

title: cryptsetup-convert(8)

text:
# cryptsetup-convert(8)

## NAME
cryptsetup-convert - converts the device between LUKS1 and LUKS2 format

## SYNOPSIS
cryptsetup convert --type <format> [<options>] <device>

## DESCRIPTION
Converts the device between LUKS1 and LUKS2 format (if possible). The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has an unsupported header size.

For conversion from LUKS2 to LUKS1, all active keyslots must use the PBKDF2 key-derivation function. The PBKDF2 and anti-forensic filter (AF) hash must be the same as the hash used in the digest. All keyslot numbers must be lower than 8 (LUKS1 maximum slot number). There must be at least one active keyslot and no unbound or reencryption keyslots.

Conversion (both directions) must be performed on an inactive device. There must not be an active dm-crypt mapping established for the LUKS header requested for conversion.

The --type option is mandatory with the following accepted values: luks1 or luks2.

WARNING: The convert action can destroy the LUKS header in the case of a crash during conversion or if a media error occurs. Always create a header backup before performing this operation!

<options> can be [--header, --type, --disable-locks].

## OPTIONS
--batch-mode, -q

Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

--debug or --debug-json

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. If --debug-json is used, additional LUKS2 JSON data structures are printed.

--disable-locks

Disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats. WARNING: Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used).

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store the ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g., luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--help, -?

Show help text and default parameters.

--type type

Specifies required device type, for more info, read the BASIC ACTIONS section in cryptsetup(8).

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-erase

title: cryptsetup-erase(8)

summary: erase all keyslots

text:
# cryptsetup-erase(8)

## NAME
cryptsetup-erase, cryptsetup-luksErase - erase all keyslots

## SYNOPSIS
cryptsetup erase [<options>] <device>

cryptsetup luksErase [<options>] <device>

## DESCRIPTION
Erase all keyslots, removing the volume key. Unless the device is configured with OPAL self-encrypting drive support, you do not need to provide any password for this operation.

This operation is irreversible. Unless you have a header backup, all old encrypted data in the container will be permanently irretrievable. Header backup cannot be used to recover data from OPAL self-encrypting drives, as the keys are permanently removed from hardware.

The erase does not wipe or overwrite the data area. It only removes all active keyslots from the LUKS device. See the cryptsetup FAQ for more information on how to wipe the whole device, including encrypted data.

Note that the --hw-opal-factory-reset option for OPAL self-encrypting drive will erase ALL data on the drive, regardless of the partition it is run on.

<options> can be [--header, --disable-locks, --hw-opal-factory-reset, --key-file].

## OPTIONS
--batch-mode, -q

Suppresses all confirmation questions. Use with care! If the --verify-passphrase option is not specified, this option also switches off the passphrase verification.

--debug or --debug-json

Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by #. If --debug-json is used, additional LUKS2 JSON data structures are printed.

--disable-locks

Disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats. WARNING: Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used).

--header <device or file storing the LUKS header>

Use to specify a detached LUKS2 header when erasing OPAL self-encrypting drive.

--help, -?

Show help text and default parameters.

--hw-opal-factory-reset

Erase ALL data on the OPAL self-encrypting drive. The option does not require a valid LUKS2 header to be present on the device to run. After providing the correct PSID via interactive prompt or via --key-file parameter the device is erased. PSID is usually printed on the OPAL drive label (either directly or as a QR code). PSID must be entered without any dashes, spaces or underscores.

PSID should be treated as sensitive information as it allows anyone with remote access to the OPAL drive to destroy data even if the device is locked. Be sure you do not leak PSID through transparent packaging during transport or images of the drive posted online.

--key-file, -d file (LUKS2 with HW OPAL only)

Read the Admin PIN or PSID (with --hw-opal-factory-reset) from the file, depending on options used. If the name given is "-", then the secret will be read from stdin. In this case, reading will not stop at newline characters.

--usage

Show short option help.

--version, -V

Show the program version.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach the output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.