nixos/modules/virtualisation/docker.nix

   1 # Systemd services for docker.
   2
   3 { config, lib, pkgs, ... }:
   4
   5 with lib;
   6
   7 let
   8
   9   cfg = config.virtualisation.docker;
  10   proxy_env = config.networking.proxy.envVars;
  11   settingsFormat = pkgs.formats.json {};
  12   daemonSettingsFile = settingsFormat.generate "daemon.json" cfg.daemon.settings;
  13 in
  14
  15 {
  16   ###### interface
  17
  18   options.virtualisation.docker = {
  19     enable =
  20       mkOption {
  21         type = types.bool;
  22         default = false;
  23         description = ''
  24             This option enables docker, a daemon that manages
  25             linux containers. Users in the "docker" group can interact with
  26             the daemon (e.g. to start or stop containers) using the
  27             {command}`docker` command line tool.
  28           '';
  29       };
  30
  31     listenOptions =
  32       mkOption {
  33         type = types.listOf types.str;
  34         default = ["/run/docker.sock"];
  35         description = ''
  36             A list of unix and tcp docker should listen to. The format follows
  37             ListenStream as described in systemd.socket(5).
  38           '';
  39       };
  40
  41     enableOnBoot =
  42       mkOption {
  43         type = types.bool;
  44         default = true;
  45         description = ''
  46             When enabled dockerd is started on boot. This is required for
  47             containers which are created with the
  48             `--restart=always` flag to work. If this option is
  49             disabled, docker might be started on demand by socket activation.
  50           '';
  51       };
  52
  53     daemon.settings =
  54       mkOption {
  55         type = types.submodule {
  56           freeformType = settingsFormat.type;
  57           options = {
  58             live-restore = mkOption {
  59               type = types.bool;
  60               # Prior to NixOS 24.11, this was set to true by default, while upstream defaulted to false.
  61               # Keep the option unset to follow upstream defaults
  62               default = versionOlder config.system.stateVersion "24.11";
  63               defaultText = literalExpression "lib.versionOlder config.system.stateVersion \"24.11\"";
  64               description = ''
  65                 Allow dockerd to be restarted without affecting running container.
  66                 This option is incompatible with docker swarm.
  67               '';
  68             };
  69           };
  70         };
  71         default = { };
  72         example = {
  73           ipv6 = true;
  74           "live-restore" = true;
  75           "fixed-cidr-v6" = "fd00::/80";
  76         };
  77         description = ''
  78           Configuration for docker daemon. The attributes are serialized to JSON used as daemon.conf.
  79           See https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file
  80         '';
  81       };
  82
  83     enableNvidia =
  84       mkOption {
  85         type = types.bool;
  86         default = false;
  87         description = ''
  88           **Deprecated**, please use hardware.nvidia-container-toolkit.enable instead.
  89
  90           Enable nvidia-docker wrapper, supporting NVIDIA GPUs inside docker containers.
  91         '';
  92       };
  93
  94     storageDriver =
  95       mkOption {
  96         type = types.nullOr (types.enum ["aufs" "btrfs" "devicemapper" "overlay" "overlay2" "zfs"]);
  97         default = null;
  98         description = ''
  99             This option determines which Docker
 100             [storage driver](https://docs.docker.com/storage/storagedriver/select-storage-driver/)
 101             to use.
 102             By default it lets docker automatically choose the preferred storage
 103             driver.
 104             However, it is recommended to specify a storage driver explicitly, as
 105             docker's default varies over versions.
 106
 107             ::: {.warning}
 108             Changing the storage driver will cause any existing containers
 109             and images to become inaccessible.
 110             :::
 111           '';
 112       };
 113
 114     logDriver =
 115       mkOption {
 116         type = types.enum ["none" "json-file" "syslog" "journald" "gelf" "fluentd" "awslogs" "splunk" "etwlogs" "gcplogs" "local"];
 117         default = "journald";
 118         description = ''
 119             This option determines which Docker log driver to use.
 120           '';
 121       };
 122
 123     extraOptions =
 124       mkOption {
 125         type = types.separatedString " ";
 126         default = "";
 127         description = ''
 128             The extra command-line options to pass to
 129             {command}`docker` daemon.
 130           '';
 131       };
 132
 133     autoPrune = {
 134       enable = mkOption {
 135         type = types.bool;
 136         default = false;
 137         description = ''
 138           Whether to periodically prune Docker resources. If enabled, a
 139           systemd timer will run `docker system prune -f`
 140           as specified by the `dates` option.
 141         '';
 142       };
 143
 144       flags = mkOption {
 145         type = types.listOf types.str;
 146         default = [];
 147         example = [ "--all" ];
 148         description = ''
 149           Any additional flags passed to {command}`docker system prune`.
 150         '';
 151       };
 152
 153       dates = mkOption {
 154         default = "weekly";
 155         type = types.str;
 156         description = ''
 157           Specification (in the format described by
 158           {manpage}`systemd.time(7)`) of the time at
 159           which the prune will occur.
 160         '';
 161       };
 162     };
 163
 164     package = mkPackageOption pkgs "docker" { };
 165
 166     extraPackages = mkOption {
 167       type = types.listOf types.package;
 168       default = [ ];
 169       example = literalExpression "with pkgs; [ criu ]";
 170       description = ''
 171         Extra packages to add to PATH for the docker daemon process.
 172       '';
 173     };
 174   };
 175
 176   imports = [
 177     (mkRemovedOptionModule ["virtualisation" "docker" "socketActivation"] "This option was removed and socket activation is now always active")
 178     (mkAliasOptionModule ["virtualisation" "docker" "liveRestore"] ["virtualisation" "docker" "daemon" "settings" "live-restore"])
 179   ];
 180
 181   ###### implementation
 182
 183   config = mkIf cfg.enable (mkMerge [{
 184       boot.kernelModules = [ "bridge" "veth" "br_netfilter" "xt_nat" ];
 185       boot.kernel.sysctl = {
 186         "net.ipv4.conf.all.forwarding" = mkOverride 98 true;
 187         "net.ipv4.conf.default.forwarding" = mkOverride 98 true;
 188       };
 189       environment.systemPackages = [ cfg.package ]
 190         ++ optional cfg.enableNvidia pkgs.nvidia-docker;
 191       users.groups.docker.gid = config.ids.gids.docker;
 192       systemd.packages = [ cfg.package ];
 193
 194       # Docker 25.0.0 supports CDI by default
 195       # (https://docs.docker.com/engine/release-notes/25.0/#new). Encourage
 196       # moving to CDI as opposed to having deprecated runtime
 197       # wrappers.
 198       warnings = lib.optionals (cfg.enableNvidia && (lib.strings.versionAtLeast cfg.package.version "25")) [
 199         ''
 200           You have set virtualisation.docker.enableNvidia. This option is deprecated, please set hardware.nvidia-container-toolkit.enable instead.
 201         ''
 202       ];
 203
 204       systemd.services.docker = {
 205         wantedBy = optional cfg.enableOnBoot "multi-user.target";
 206         after = [ "network.target" "docker.socket" ];
 207         requires = [ "docker.socket" ];
 208         environment = proxy_env;
 209         serviceConfig = {
 210           Type = "notify";
 211           ExecStart = [
 212             ""
 213             ''
 214               ${cfg.package}/bin/dockerd \
 215                 --config-file=${daemonSettingsFile} \
 216                 ${cfg.extraOptions}
 217             ''];
 218           ExecReload=[
 219             ""
 220             "${pkgs.procps}/bin/kill -s HUP $MAINPID"
 221           ];
 222         };
 223
 224         path = [ pkgs.kmod ] ++ optional (cfg.storageDriver == "zfs") pkgs.zfs
 225           ++ optional cfg.enableNvidia pkgs.nvidia-docker
 226           ++ cfg.extraPackages;
 227       };
 228
 229       systemd.sockets.docker = {
 230         description = "Docker Socket for the API";
 231         wantedBy = [ "sockets.target" ];
 232         socketConfig = {
 233           ListenStream = cfg.listenOptions;
 234           SocketMode = "0660";
 235           SocketUser = "root";
 236           SocketGroup = "docker";
 237         };
 238       };
 239
 240       systemd.services.docker-prune = {
 241         description = "Prune docker resources";
 242
 243         restartIfChanged = false;
 244         unitConfig.X-StopOnRemoval = false;
 245
 246         serviceConfig.Type = "oneshot";
 247
 248         script = ''
 249           ${cfg.package}/bin/docker system prune -f ${toString cfg.autoPrune.flags}
 250         '';
 251
 252         startAt = optional cfg.autoPrune.enable cfg.autoPrune.dates;
 253         after = [ "docker.service" ];
 254         requires = [ "docker.service" ];
 255       };
 256
 257       assertions = [
 258         { assertion = cfg.enableNvidia && pkgs.stdenv.hostPlatform.isx86_64 -> config.hardware.graphics.enable32Bit or false;
 259           message = "Option enableNvidia on x86_64 requires 32-bit support libraries";
 260         }];
 261
 262       virtualisation.docker.daemon.settings = {
 263         group = "docker";
 264         hosts = [ "fd://" ];
 265         log-driver = mkDefault cfg.logDriver;
 266         storage-driver = mkIf (cfg.storageDriver != null) (mkDefault cfg.storageDriver);
 267         runtimes = mkIf cfg.enableNvidia {
 268           nvidia = {
 269             # Use the legacy nvidia-container-runtime wrapper to allow
 270             # the `--runtime=nvidia` approach to expose
 271             # GPU's. Starting with Docker > 25, CDI can be used
 272             # instead, removing the need for runtime wrappers.
 273             path = lib.getExe' pkgs.nvidia-docker "nvidia-container-runtime.legacy";
 274           };
 275         };
 276       };
 277     }
 278   ]);
 279 }