nixos: use user service for activation

systemd: remove unneeded XDG_RUNTIME_DIR workaround

nixos: documentation about home manager status

nixos: use enable for ssh_config units

docs/installation.adoc

@@ -0,0 +1,355 @@
+[[ch-installation]]
+== Installing Home Manager
+
+:nix-darwin: https://github.com/LnL7/nix-darwin/
+:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
+
+Home Manager can be used in three primary ways:
+
+1. Using the standalone `home-manager` tool. For platforms other than
+NixOS and Darwin, this is the only available choice. It is also
+recommended for people on NixOS or Darwin that want to manage their
+home directory independently of the system as a whole. See
+<<sec-install-standalone>> for instructions on how to perform this
+installation.
+
+2. As a module within a NixOS system configuration. This allows the
+user profiles to be built together with the system when running
+`nixos-rebuild`. See <<sec-install-nixos-module>> for a description of
+this setup.
+
+3. As a module within a {nix-darwin}[nix-darwin] system configuration.
+This allows the user profiles to be built together with the system
+when running `darwin-rebuild`. See <<sec-install-nix-darwin-module>>
+for a description of this setup.
+
+[NOTE]
+In this chapter we describe how to install Home Manager in the
+standard way using channels. If you prefer to use
+{nixos-wiki-flakes}[Nix Flakes] then please see the instructions in
+<<ch-nix-flakes>>.
+
+[[sec-install-standalone]]
+=== Standalone installation
+
+:nix-allowed-users: https://nixos.org/nix/manual/#conf-allowed-users
+:nixos-allowed-users: https://nixos.org/manual/nixos/stable/options.html#opt-nix.settings.allowed-users
+:bash: https://www.gnu.org/software/bash/
+:zsh: http://zsh.sourceforge.net/
+:fish: https://fishshell.com
+:plugin-foreign-env: https://github.com/oh-my-fish/plugin-foreign-env
+:babelfish: https://github.com/bouk/babelfish
+
+1. Make sure you have a working Nix installation. Specifically, make
+sure that your user is able to build and install Nix packages. For
+example, you should be able to successfully run a command like
+`nix-instantiate '<nixpkgs>' -A hello` without having to switch to the
+root user. For a multi-user install of Nix this means that your user
+must be covered by the {nix-allowed-users}[`allowed-users`] Nix
+option. On NixOS you can control this option using the
+{nixos-allowed-users}[`nix.settings.allowed-users`] system option.
+
+2. Add the appropriate Home Manager channel. If you are following
+Nixpkgs master or an unstable channel you can run
++
+[source,console]
+----
+$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
+$ nix-channel --update
+----
++
+and if you follow a Nixpkgs version 23.05 channel you can run
++
+[source,console]
+----
+$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
+$ nix-channel --update
+----
+
+3. Run the Home Manager installation command and create the first Home
+Manager generation:
++
+[source,console]
+$ nix-shell '<home-manager>' -A install
++
+Once finished, Home Manager should be active and available in your
+user environment.
+
+4. If you do not plan on having Home Manager manage your shell
+configuration then you must source the
++
+[source,bash]
+$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh
++
+file in your shell configuration. Alternatively source
++
+[source,bash]
+/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh
++
+when managing home configuration together with system configuration.
++
+This file can be sourced directly by POSIX.2-like shells such as
+{bash}[Bash] or {zsh}[Z shell]. {fish}[Fish] users can use utilities
+such as {plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
++
+For example, if you use Bash then add
++
+[source,bash]
+----
+. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
+----
++
+to your `~/.profile` file.
+
+If instead of using channels you want to run Home Manager from a Git
+checkout of the repository then you can use the
+<<opt-programs.home-manager.path>> option to specify the absolute path
+to the repository.
+
+Once installed you can see <<ch-usage>> for a more detailed
+description of Home Manager and how to use it.
+
+[[sec-install-nixos-module]]
+=== NixOS module
+
+Home Manager provides a NixOS module that allows you to prepare user
+environments directly from the system configuration file, which often
+is more convenient than using the `home-manager` tool. It also opens
+up additional possibilities, for example, to automatically configure
+user environments in NixOS declarative containers or on systems
+deployed through NixOps.
+
+To make the NixOS module available for use you must `import` it into
+your system configuration. This is most conveniently done by adding a
+Home Manager channel to the root user. For example, if you are
+following Nixpkgs master or an unstable channel, you can run
+
+[source,console]
+----
+$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
+$ sudo nix-channel --update
+----
+
+and if you follow a Nixpkgs version 23.05 channel, you can run
+
+[source,console]
+----
+$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
+$ sudo nix-channel --update
+----
+
+It is then possible to add
+
+[source,nix]
+imports = [ <home-manager/nixos> ];
+
+to your system `configuration.nix` file, which will introduce a new
+NixOS option called `home-manager.users` whose type is an attribute
+set that maps user names to Home Manager configurations.
+
+For example, a NixOS configuration may include the lines
+
+[source,nix]
+----
+users.users.eve.isNormalUser = true;
+home-manager.users.eve = { pkgs, ... }: {
+  home.packages = [ pkgs.atool pkgs.httpie ];
+  programs.bash.enable = true;
+
+  # The state version is required and should stay at the version you
+  # originally installed.
+  home.stateVersion = "23.05";
+};
+----
+
+and after a `sudo nixos-rebuild switch` the user eve's environment should
+include a basic Bash configuration and the packages atool and httpie.
+
+[NOTE]
+====
+If after a `nixos-rebuild switch` you *don't* have the environment
+you expect, you can take a look at home-manager's output with
+[source,bash]
+journalctl SYSLOG_IDENTIFIER=hm-activate-$USER
+====
+
+If you do not plan on having Home Manager manage your shell
+configuration then you must add either
+
+[source,bash]
+----
+. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
+----
+
+or
+
+[source,bash]
+----
+. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
+----
+
+to your shell configuration, depending on whether
+<<nixos-opt-home-manager.useUserPackages>> is enabled. This file can
+be sourced directly by POSIX.2-like shells such as {bash}[Bash] or
+{zsh}[Z shell]. {fish}[Fish] users can use utilities such as
+{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
+
+[NOTE]
+====
+By default packages will be installed to `$HOME/.nix-profile` but they
+can be installed to `/etc/profiles` if
+
+[source,nix]
+home-manager.useUserPackages = true;
+
+is added to the system configuration. This is necessary if, for
+example, you wish to use `nixos-rebuild build-vm`. This option may
+become the default value in the future.
+====
+
+[NOTE]
+====
+By default, Home Manager uses a private `pkgs` instance that is
+configured via the `home-manager.users.<name>.nixpkgs` options. To
+instead use the global `pkgs` that is configured via the system level
+`nixpkgs` options, set
+
+[source,nix]
+home-manager.useGlobalPkgs = true;
+
+This saves an extra Nixpkgs evaluation, adds consistency, and removes
+the dependency on `NIX_PATH`, which is otherwise used for importing
+Nixpkgs.
+====
+
+[NOTE]
+====
+Home Manager will pass `osConfig` as a module argument to any modules
+you create. This contains the system's NixOS configuration.
+
+[source,nix]
+{ lib, pkgs, osConfig, ... }:
+====
+
+Once installed you can see <<ch-usage>> for a more detailed
+description of Home Manager and how to use it.
+
+[[sec-install-nix-darwin-module]]
+=== nix-darwin module
+
+Home Manager provides a module that allows you to prepare user
+environments directly from the {nix-darwin}[nix-darwin] configuration
+file, which often is more convenient than using the `home-manager`
+tool.
+
+To make the NixOS module available for use you must `import` it into
+your system configuration. This is most conveniently done by adding a
+Home Manager channel. For example, if you are following Nixpkgs master
+or an unstable channel, you can run
+
+[source,console]
+----
+$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
+$ nix-channel --update
+----
+
+and if you follow a Nixpkgs version 23.05 channel, you can run
+
+[source,console]
+----
+$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
+$ nix-channel --update
+----
+
+It is then possible to add
+
+[source,nix]
+imports = [ <home-manager/nix-darwin> ];
+
+to your nix-darwin `configuration.nix` file, which will introduce a
+new NixOS option called `home-manager` whose type is an attribute set
+that maps user names to Home Manager configurations.
+
+For example, a nix-darwin configuration may include the lines
+
+[source,nix]
+----
+users.users.eve = {
+  name = "eve";
+  home = "/Users/eve";
+}
+home-manager.users.eve = { pkgs, ... }: {
+  home.packages = [ pkgs.atool pkgs.httpie ];
+  programs.bash.enable = true;
+
+  # The state version is required and should stay at the version you
+  # originally installed.
+  home.stateVersion = "23.05";
+};
+----
+
+and after a `darwin-rebuild switch` the user eve's environment
+should include a basic Bash configuration and the packages atool and
+httpie.
+
+If you do not plan on having Home Manager manage your shell
+configuration then you must add either
+
+[source,bash]
+----
+. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
+----
+
+or
+
+[source,bash]
+----
+. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
+----
+
+to your shell configuration, depending on whether
+<<nix-darwin-opt-home-manager.useUserPackages>> is enabled. This file
+can be sourced directly by POSIX.2-like shells such as {bash}[Bash] or
+{zsh}[Z shell]. {fish}[Fish] users can use utilities such as
+{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
+
+[NOTE]
+====
+By default user packages will not be ignored in favor of
+`environment.systemPackages`, but they will be installed to
+`/etc/profiles/per-user/$USERNAME` if
+
+[source,nix]
+home-manager.useUserPackages = true;
+
+is added to the nix-darwin configuration. This option may become the
+default value in the future.
+====
+
+[NOTE]
+====
+By default, Home Manager uses a private `pkgs` instance that is
+configured via the `home-manager.users.<name>.nixpkgs` options. To
+instead use the global `pkgs` that is configured via the system level
+`nixpkgs` options, set
+
+[source,nix]
+home-manager.useGlobalPkgs = true;
+
+This saves an extra Nixpkgs evaluation, adds consistency, and removes
+the dependency on `NIX_PATH`, which is otherwise used for importing
+Nixpkgs.
+====
+
+[NOTE]
+====
+Home Manager will pass `osConfig` as a module argument to any modules
+you create. This contains the system's nix-darwin configuration.
+
+[source,nix]
+{ lib, pkgs, osConfig, ... }:
+====
+
+Once installed you can see <<ch-usage>> for a more detailed
+description of Home Manager and how to use it.
+

modules/programs/ssh.nix

@@ -496,6 +496,23 @@ in
         for more information.
       '';
     };
+
+    configPath = mkOption {
+      type = types.path;
+      internal = true;
+      description = ''
+        Path to the ssh configuration.
+      '';
+    };
+
+    internallyManaged = mkOption {
+      type = types.bool;
+      default = true;
+      internal = true;
+      description = ''
+        Whether to link .ssh/config to programs.ssh.configPath
+      '';
+    };
   };
 
   config = mkIf cfg.enable {
@@ -520,15 +537,17 @@ in
 
     home.packages = optional (cfg.package != null) cfg.package;
 
-    home.file.".ssh/config".text =
+    home.file.".ssh/config".source = mkIf cfg.internallyManaged cfg.configPath;
+
+    programs.ssh.configPath =
       let
         sortedMatchBlocks = hm.dag.topoSort cfg.matchBlocks;
         sortedMatchBlocksStr = builtins.toJSON sortedMatchBlocks;
         matchBlocks =
           if sortedMatchBlocks ? result
           then sortedMatchBlocks.result
           else abort "Dependency cycle in SSH match blocks: ${sortedMatchBlocksStr}";
-      in ''
+      in pkgs.writeText "ssh_config" ''
       ${concatStringsSep "\n" (
         (mapAttrsToList (n: v: "${n} ${v}") cfg.extraOptionOverrides)
         ++ (optional (cfg.includes != [ ]) ''