github.com/containerd/nerdctl@v1.7.7/docs/rootless.md (about)

     1  # Rootless mode
     2  
     3  See https://rootlesscontaine.rs/getting-started/common/ for the prerequisites.
     4  
     5  ## Daemon (containerd)
     6  
     7  Use [`containerd-rootless-setuptool.sh`](../extras/rootless) to set up rootless containerd.
     8  
     9  ```console
    10  $ containerd-rootless-setuptool.sh install
    11  [INFO] Checking RootlessKit functionality
    12  [INFO] Checking cgroup v2
    13  [INFO] Checking overlayfs
    14  [INFO] Creating /home/testuser/.config/systemd/user/containerd.service
    15  ...
    16  [INFO] Installed containerd.service successfully.
    17  [INFO] To control containerd.service, run: `systemctl --user (start|stop|restart) containerd.service`
    18  [INFO] To run containerd.service on system startup, run: `sudo loginctl enable-linger testuser`
    19  
    20  [INFO] Use `nerdctl` to connect to the rootless containerd.
    21  [INFO] You do NOT need to specify $CONTAINERD_ADDRESS explicitly.
    22  ```
    23  
    24  The usage of `containerd-rootless-setuptool.sh` is almost same as [`dockerd-rootless-setuptool.sh`](https://rootlesscontaine.rs/getting-started/docker/) .
    25  
    26  Resource limitation flags such as `nerdctl run --memory` require systemd and cgroup v2: https://rootlesscontaine.rs/getting-started/common/cgroup2/
    27  
    28  ## Client (nerdctl)
    29  
    30  Just execute `nerdctl`. No need to specify the socket address manually.
    31  
    32  ```console
    33  $ nerdctl run -it --rm alpine
    34  ```
    35  
    36  Depending on your kernel version, you may need to enable FUSE-OverlayFS or set `export CONTAINERD_SNAPSHOTTER=native`.
    37  (See below.)
    38  
    39  ## Add-ons
    40  ### BuildKit
    41  To enable BuildKit, run the following command:
    42  
    43  ```console
    44  $ containerd-rootless-setuptool.sh install-buildkit
    45  ```
    46  
    47  ## Snapshotters
    48  
    49  ### OverlayFS
    50  
    51  The default `overlayfs` snapshotter only works on the following hosts:
    52  - Any distro, with kernel >= 5.13
    53  - Non-SELinux distro, with kernel >= 5.11
    54  - Ubuntu since 2015
    55  
    56  For other hosts, [`fuse-overlayfs` snapshotter](https://github.com/containerd/fuse-overlayfs-snapshotter) needs to be used instead.
    57  
    58  ### FUSE-OverlayFS
    59  
    60  To enable `fuse-overlayfs` snapshotter, run the following command:
    61  ```console
    62  $ containerd-rootless-setuptool.sh install-fuse-overlayfs
    63  ```
    64  
    65  Then, add the following config to `~/.config/containerd/config.toml`, and run `systemctl --user restart containerd.service`:
    66  ```toml
    67  [proxy_plugins]
    68    [proxy_plugins."fuse-overlayfs"]
    69        type = "snapshot"
    70  # NOTE: replace "1000" with your actual UID
    71        address = "/run/user/1000/containerd-fuse-overlayfs.sock"
    72  ```
    73  
    74  The snapshotter can be specified as `$CONTAINERD_SNAPSHOTTER`.
    75  ```console
    76  $ export CONTAINERD_SNAPSHOTTER=fuse-overlayfs
    77  $ nerdctl run -it --rm alpine
    78  ```
    79  
    80  If `fuse-overlayfs` does not work, try `export CONTAINERD_SNAPSHOTTER=native`.
    81  
    82  ### Stargz Snapshotter
    83  [Stargz Snapshotter](./stargz.md) enables lazy-pulling of images.
    84  
    85  To enable Stargz snapshotter, run the following command:
    86  ```console
    87  $ containerd-rootless-setuptool.sh install-stargz
    88  ```
    89  
    90  Then, add the following config to `~/.config/containerd/config.toml` and run `systemctl --user restart containerd.service`:
    91  ```toml
    92  [proxy_plugins]
    93    [proxy_plugins."stargz"]
    94        type = "snapshot"
    95  # NOTE: replace "1000" with your actual UID
    96        address = "/run/user/1000/containerd-stargz-grpc/containerd-stargz-grpc.sock"
    97  ```
    98  
    99  The snapshotter can be specified as `$CONTAINERD_SNAPSHOTTER`.
   100  ```console
   101  $ export CONTAINERD_SNAPSHOTTER=stargz
   102  $ nerdctl run -it --rm ghcr.io/stargz-containers/alpine:3.10.2-esgz
   103  ```
   104  
   105  See https://github.com/containerd/stargz-snapshotter/blob/main/docs/pre-converted-images.md for the image list.
   106  
   107  ## bypass4netns
   108  | :zap: Requirement | nerdctl >= 0.17 |
   109  |-------------------|-----------------|
   110  
   111  
   112  [bypass4netns(https://github.com/rootless-containers/bypass4netns)](https://github.com/rootless-containers/bypass4netns) is an accelerator for rootless networking.
   113  
   114  This improves **outgoing or incoming (with --publish option) networking performance.**
   115  
   116  The performance benchmark with iperf3 on Ubuntu 21.10 on Hyper-V VM is shown below.
   117  | iperf3 benchmark  | without bypass4netns | with bypass4netns |
   118  | ----------------- | -------------------- | ----------------- |
   119  | container -> host | 0.398 Gbps           | **42.2 Gbps**         |
   120  | host -> container | 20.6 Gbps             | **47.4 Gbps**         |
   121  
   122  This benchmark can be reproduced with [https://github.com/rootless-containers/bypass4netns/blob/f009d96139e9e38ce69a2ea8a9a746349bad273c/Vagrantfile](https://github.com/rootless-containers/bypass4netns/blob/f009d96139e9e38ce69a2ea8a9a746349bad273c/Vagrantfile)
   123  
   124  Acceleration with bypass4netns is available with `--label nerdctl/bypass4netns=true`. You also need to have `bypass4netnsd` (bypass4netns daemon) to be running.
   125  Example
   126  ```console
   127  $ containerd-rootless-setuptool.sh install-bypass4netnsd
   128  $ nerdctl run -it --rm -p 8080:80 --label nerdctl/bypass4netns=true alpine
   129  ```
   130  
   131  More detail is available at [https://github.com/rootless-containers/bypass4netns/blob/master/README.md](https://github.com/rootless-containers/bypass4netns/blob/master/README.md)
   132  
   133  ## Troubleshooting
   134  
   135  ### Hint to Fedora users
   136  - If SELinux is enabled on your host and your kernel is older than 5.13, you need to use [`fuse-overlayfs` instead of `overlayfs`](#fuse-overlayfs).