mirror of
https://github.com/linuxkit/linuxkit.git
synced 2026-04-06 08:02:38 +00:00
aebd255755
Update examples/swap.yml to use latest linuxkit/swap image Add comment to examples/swap.yml how to enable encryption Add encrypt options to README Make encrypted swap the default Signed-off-by: Avi Deitcher <avi@deitcher.net>
93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# LinuxKit Swap
|
|
Image to enable creation of a swap file for a [linuxkit](https://github.com/linuxkit/linuxkit)-generated image.
|
|
|
|
|
|
## Usage
|
|
Normally, unless you are running explicitly in a desktop version, LinuxKit images do not have swap enabled. If you want swap, add the following to your `moby.yml`:
|
|
|
|
```
|
|
onboot:
|
|
- name: swap
|
|
image: "linuxkit/swap:a881d50445ea27624be67dcda39313e7a2051982"
|
|
net: host
|
|
pid: host
|
|
capabilities:
|
|
- CAP_SYS_ADMIN
|
|
- CAP_MKNOD
|
|
readonly: true
|
|
binds:
|
|
- /dev:/dev
|
|
- /var:/var
|
|
command: ["swap.sh","--path","/var/external/swap","--size","2G"]
|
|
```
|
|
|
|
Note that you **nust** mount the following:
|
|
|
|
* `/var` to `/var` so it can place the swapfile in the right location.
|
|
* `/dev` to `/dev` so it can do the right thing for devices
|
|
|
|
### Options
|
|
|
|
Options are passed to it via command-line options. The following are the options. Details follow.
|
|
|
|
|Option|Parameter|Default|Required|Notes|
|
|
|---|---|---|---|---|
|
|
|`--path`|Path to file as seen in the underlying OS||**Yes**||
|
|
|`--size`|Target swapfile size||**Yes**||
|
|
|`--condition`|_condition_||No|Condition that must be met to create a swapfile|
|
|
|`--debug`|||No|Turns on verbose output from the command making the swap|
|
|
|`--encrypt`|||No|Encrypts swapfile|
|
|
|
|
|
|
#### File
|
|
You can create a swapfile at the given path. You **must** provide exactly one swapfile path, or none will be created; there is no default. Passing fewer than or more than one `--path` option causes the container to exit with an error.
|
|
|
|
The option `--path` takes a single argument _path_, path to the swapfile, e.g. `/var/mnt/swap2`.
|
|
|
|
You **always** should put the swap file somewhere under `/var`, since that is where read-writable files and mounts exist in linuxkit images.
|
|
|
|
#### Size
|
|
`--size <size>` indicates the desired swapfile size, e.g. `2G` `100M` `5670K` `8765432`. There is no default. Acceptable size units are `G`, `M`, `K` and bytes of no unit provided.
|
|
|
|
If disk space on the requested partition is insufficient to create the swapfile, the container exits with an error.
|
|
|
|
#### Encryption
|
|
If you want the swapfile to be encrypted, pass the `--encrypt` option. It will create an encrypted swapfile at the path you provide to `--path`, using devicemapper to map the clear device to `/dev/mapper/swapfile`.
|
|
|
|
Encryption is performed using `cryptsetup` with `plain` encryption, using `/dev/urandom` to generate a random keyfile, key size of `256`, and cipher `aes-cbc-essiv:sha256`.
|
|
|
|
#### Conditions
|
|
You may want to create a swapfile only if certain conditions are met. Supported conditions are:
|
|
|
|
* An external disk is available
|
|
* Partition on which the swapfile will sit is of a minimum size.
|
|
|
|
**All** conditions must be met. If a condition fails, the swapfile is not created, but the container exits with no error, unless you set the condition as `required`.
|
|
|
|
Conditions are structured as follows: _type_:_parameter_:_required_
|
|
|
|
In all cases, you may leave off _required_ if you wish to treat it as false, i.e. do not create swapfile but exit with no error if the condition is not met.
|
|
|
|
##### Partition exists
|
|
LinuxKit may be running from a small disk, and you only want to run if a particular large external disk is available. In that case, pass `--condition part:<path>:<required>` to indicate that swapfile is to be created only if _path_ already exists and is a mount point.
|
|
|
|
Example: `--condition part:/var/mnt/external`
|
|
|
|
##### Size
|
|
You may set a minimum size for a partition (likely the one on which the swapfile will be created) using the `size` condition of the format `--condition size:<path>:<size>:<required>` to indicate that swapfile is to be created only if the partition on which _path_ exists is of minimum size _size_. Acceptable sizes are identical to those for the swapfile.
|
|
|
|
Examples:
|
|
|
|
* `--condition partsize:/var/mnt/external:100G:true`
|
|
|
|
|
|
## Example
|
|
An example yml file is included in [examples/swap.yml](../../examples/swap.yml). `swap.yml`. Note that you need to attach an external disk - trying to create a swapfile in tmpfs `/var` will fail.
|
|
|
|
The sample command to run the enclosed is:
|
|
|
|
```
|
|
moby build swap.yml
|
|
moby run -disk-size 4096 swap
|
|
```
|