From a55f0640b037a6d0771367622bd44996b8c74330 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:36:14 +0800 Subject: [PATCH 01/10] nixos: nixos/doc/manual/configuration/user-mgmt.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../manual/configuration/user-mgmt.chapter.md | 92 +++++++++++++++ nixos/doc/manual/configuration/user-mgmt.xml | 88 -------------- .../configuration/user-mgmt.chapter.xml | 107 ++++++++++++++++++ 4 files changed, 200 insertions(+), 89 deletions(-) create mode 100644 nixos/doc/manual/configuration/user-mgmt.chapter.md delete mode 100644 nixos/doc/manual/configuration/user-mgmt.xml create mode 100644 nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 6949189b8883..006205215f6e 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -15,7 +15,7 @@ - + diff --git a/nixos/doc/manual/configuration/user-mgmt.chapter.md b/nixos/doc/manual/configuration/user-mgmt.chapter.md new file mode 100644 index 000000000000..64eacc5f7dd6 --- /dev/null +++ b/nixos/doc/manual/configuration/user-mgmt.chapter.md @@ -0,0 +1,92 @@ +# User Management {#sec-user-management} + +NixOS supports both declarative and imperative styles of user +management. In the declarative style, users are specified in +`configuration.nix`. For instance, the following states that a user +account named `alice` shall exist: + +```nix +users.users.alice = { + isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; +``` + +Note that `alice` is a member of the `wheel` and `networkmanager` +groups, which allows her to use `sudo` to execute commands as `root` and +to configure the network, respectively. Also note the SSH public key +that allows remote logins with the corresponding private key. Users +created in this way do not have a password by default, so they cannot +log in via mechanisms that require a password. However, you can use the +`passwd` program to set a password, which is retained across invocations +of `nixos-rebuild`. + +If you set [`users.mutableUsers`](options.html#opt-users.mutableUsers) to +false, then the contents of `/etc/passwd` and `/etc/group` will be congruent +to your NixOS configuration. For instance, if you remove a user from +[`users.users`](options.html#opt-users.users) and run nixos-rebuild, the user +account will cease to exist. Also, imperative commands for managing users and +groups, such as useradd, are no longer available. Passwords may still be +assigned by setting the user\'s +[hashedPassword](#opt-users.users._name_.hashedPassword) option. A +hashed password can be generated using `mkpasswd -m + sha-512`. + +A user ID (uid) is assigned automatically. You can also specify a uid +manually by adding + +```nix +uid = 1000; +``` + +to the user specification. + +Groups can be specified similarly. The following states that a group +named `students` shall exist: + +```nix +users.groups.students.gid = 1000; +``` + +As with users, the group ID (gid) is optional and will be assigned +automatically if it's missing. + +In the imperative style, users and groups are managed by commands such +as `useradd`, `groupmod` and so on. For instance, to create a user +account named `alice`: + +```ShellSession +# useradd -m alice +``` + +To make all nix tools available to this new user use \`su - USER\` which +opens a login shell (==shell that loads the profile) for given user. +This will create the \~/.nix-defexpr symlink. So run: + +```ShellSession +# su - alice -c "true" +``` + +The flag `-m` causes the creation of a home directory for the new user, +which is generally what you want. The user does not have an initial +password and therefore cannot log in. A password can be set using the +`passwd` utility: + +```ShellSession +# passwd alice +Enter new UNIX password: *** +Retype new UNIX password: *** +``` + +A user can be deleted using `userdel`: + +```ShellSession +# userdel -r alice +``` + +The flag `-r` deletes the user's home directory. Accounts can be +modified using `usermod`. Unix groups can be managed using `groupadd`, +`groupmod` and `groupdel`. diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml deleted file mode 100644 index e83e7b75ef54..000000000000 --- a/nixos/doc/manual/configuration/user-mgmt.xml +++ /dev/null @@ -1,88 +0,0 @@ - - User Management - - NixOS supports both declarative and imperative styles of user management. In - the declarative style, users are specified in - configuration.nix. For instance, the following states - that a user account named alice shall exist: - -.alice = { - isNormalUser = true; - home = "/home/alice"; - description = "Alice Foobar"; - extraGroups = [ "wheel" "networkmanager" ]; - openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; -}; - - Note that alice is a member of the - wheel and networkmanager groups, which - allows her to use sudo to execute commands as - root and to configure the network, respectively. Also note - the SSH public key that allows remote logins with the corresponding private - key. Users created in this way do not have a password by default, so they - cannot log in via mechanisms that require a password. However, you can use - the passwd program to set a password, which is retained - across invocations of nixos-rebuild. - - - If you set to false, then the - contents of /etc/passwd and /etc/group - will be congruent to your NixOS configuration. For instance, if you remove a - user from and run nixos-rebuild, the user - account will cease to exist. Also, imperative commands for managing users and - groups, such as useradd, are no longer available. Passwords may still be - assigned by setting the user's - hashedPassword - option. A hashed password can be generated using mkpasswd -m - sha-512. - - - A user ID (uid) is assigned automatically. You can also specify a uid - manually by adding - -uid = 1000; - - to the user specification. - - - Groups can be specified similarly. The following states that a group named - students shall exist: - -.students.gid = 1000; - - As with users, the group ID (gid) is optional and will be assigned - automatically if it’s missing. - - - In the imperative style, users and groups are managed by commands such as - useradd, groupmod and so on. For - instance, to create a user account named alice: - -# useradd -m alice - To make all nix tools available to this new user use `su - USER` which opens - a login shell (==shell that loads the profile) for given user. This will - create the ~/.nix-defexpr symlink. So run: - -# su - alice -c "true" - The flag causes the creation of a home directory for the - new user, which is generally what you want. The user does not have an initial - password and therefore cannot log in. A password can be set using the - passwd utility: - -# passwd alice -Enter new UNIX password: *** -Retype new UNIX password: *** - - A user can be deleted using userdel: - -# userdel -r alice - The flag deletes the user’s home directory. Accounts - can be modified using usermod. Unix groups can be managed - using groupadd, groupmod and - groupdel. - - diff --git a/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml new file mode 100644 index 000000000000..b865fabfe3cc --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml @@ -0,0 +1,107 @@ + + User Management + + NixOS supports both declarative and imperative styles of user + management. In the declarative style, users are specified in + configuration.nix. For instance, the following + states that a user account named alice shall + exist: + + +users.users.alice = { + isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; + + + Note that alice is a member of the + wheel and networkmanager + groups, which allows her to use sudo to execute + commands as root and to configure the network, + respectively. Also note the SSH public key that allows remote logins + with the corresponding private key. Users created in this way do not + have a password by default, so they cannot log in via mechanisms + that require a password. However, you can use the + passwd program to set a password, which is + retained across invocations of nixos-rebuild. + + + If you set + users.mutableUsers + to false, then the contents of /etc/passwd and + /etc/group will be congruent to your NixOS + configuration. For instance, if you remove a user from + users.users + and run nixos-rebuild, the user account will cease to exist. Also, + imperative commands for managing users and groups, such as useradd, + are no longer available. Passwords may still be assigned by setting + the user's + hashedPassword + option. A hashed password can be generated using + mkpasswd -m sha-512. + + + A user ID (uid) is assigned automatically. You can also specify a + uid manually by adding + + +uid = 1000; + + + to the user specification. + + + Groups can be specified similarly. The following states that a group + named students shall exist: + + +users.groups.students.gid = 1000; + + + As with users, the group ID (gid) is optional and will be assigned + automatically if it’s missing. + + + In the imperative style, users and groups are managed by commands + such as useradd, groupmod and + so on. For instance, to create a user account named + alice: + + +# useradd -m alice + + + To make all nix tools available to this new user use `su - USER` + which opens a login shell (==shell that loads the profile) for given + user. This will create the ~/.nix-defexpr symlink. So run: + + +# su - alice -c "true" + + + The flag -m causes the creation of a home + directory for the new user, which is generally what you want. The + user does not have an initial password and therefore cannot log in. + A password can be set using the passwd utility: + + +# passwd alice +Enter new UNIX password: *** +Retype new UNIX password: *** + + + A user can be deleted using userdel: + + +# userdel -r alice + + + The flag -r deletes the user’s home directory. + Accounts can be modified using usermod. Unix + groups can be managed using groupadd, + groupmod and groupdel. + + From 361056334d9ceefb607c6f49068c2d4ead59a6cb Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:37:18 +0800 Subject: [PATCH 02/10] nixos: nixos/doc/manual/configuration/x-windows.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../manual/configuration/x-windows.chapter.md | 337 +++++++++++++++ nixos/doc/manual/configuration/x-windows.xml | 355 ---------------- .../configuration/x-windows.chapter.xml | 383 ++++++++++++++++++ 4 files changed, 721 insertions(+), 356 deletions(-) create mode 100644 nixos/doc/manual/configuration/x-windows.chapter.md delete mode 100644 nixos/doc/manual/configuration/x-windows.xml create mode 100644 nixos/doc/manual/from_md/configuration/x-windows.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 006205215f6e..4598ae4d1399 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -17,7 +17,7 @@ - + diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md new file mode 100644 index 000000000000..d9a924d41d7d --- /dev/null +++ b/nixos/doc/manual/configuration/x-windows.chapter.md @@ -0,0 +1,337 @@ +# X Window System {#sec-x11} + +The X Window System (X11) provides the basis of NixOS' graphical user +interface. It can be enabled as follows: + +```nix +services.xserver.enable = true; +``` + +The X server will automatically detect and use the appropriate video +driver from a set of X.org drivers (such as `vesa` and `intel`). You can +also specify a driver manually, e.g. + +```nix +services.xserver.videoDrivers = [ "r128" ]; +``` + +to enable X.org's `xf86-video-r128` driver. + +You also need to enable at least one desktop or window manager. +Otherwise, you can only log into a plain undecorated `xterm` window. +Thus you should pick one or more of the following lines: + +```nix +services.xserver.desktopManager.plasma5.enable = true; +services.xserver.desktopManager.xfce.enable = true; +services.xserver.desktopManager.gnome.enable = true; +services.xserver.desktopManager.mate.enable = true; +services.xserver.windowManager.xmonad.enable = true; +services.xserver.windowManager.twm.enable = true; +services.xserver.windowManager.icewm.enable = true; +services.xserver.windowManager.i3.enable = true; +services.xserver.windowManager.herbstluftwm.enable = true; +``` + +NixOS's default *display manager* (the program that provides a graphical +login prompt and manages the X server) is LightDM. You can select an +alternative one by picking one of the following lines: + +```nix +services.xserver.displayManager.sddm.enable = true; +services.xserver.displayManager.gdm.enable = true; +``` + +You can set the keyboard layout (and optionally the layout variant): + +```nix +services.xserver.layout = "de"; +services.xserver.xkbVariant = "neo"; +``` + +The X server is started automatically at boot time. If you don't want +this to happen, you can set: + +```nix +services.xserver.autorun = false; +``` + +The X server can then be started manually: + +```ShellSession +# systemctl start display-manager.service +``` + +On 64-bit systems, if you want OpenGL for 32-bit programs such as in +Wine, you should also set the following: + +```nix +hardware.opengl.driSupport32Bit = true; +``` + +## Auto-login {#sec-x11-auto-login .unnumbered} + +The x11 login screen can be skipped entirely, automatically logging you +into your window manager and desktop environment when you boot your +computer. + +This is especially helpful if you have disk encryption enabled. Since +you already have to provide a password to decrypt your disk, entering a +second password to login can be redundant. + +To enable auto-login, you need to define your default window manager and +desktop environment. If you wanted no desktop environment and i3 as your +your window manager, you\'d define: + +```nix +services.xserver.displayManager.defaultSession = "none+i3"; +``` + +Every display manager in NixOS supports auto-login, here is an example +using lightdm for a user `alice`: + +```nix +services.xserver.displayManager.lightdm.enable = true; +services.xserver.displayManager.autoLogin.enable = true; +services.xserver.displayManager.autoLogin.user = "alice"; +``` + +## Intel Graphics drivers {#sec-x11--graphics-cards-intel .unnumbered} + +There are two choices for Intel Graphics drivers in X.org: `modesetting` +(included in the xorg-server itself) and `intel` (provided by the +package xf86-video-intel). + +The default and recommended is `modesetting`. It is a generic driver +which uses the kernel [mode +setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism. It +supports Glamor (2D graphics acceleration via OpenGL) and is actively +maintained but may perform worse in some cases (like in old chipsets). + +The second driver, `intel`, is specific to Intel GPUs, but not +recommended by most distributions: it lacks several modern features (for +example, it doesn\'t support Glamor) and the package hasn\'t been +officially updated since 2015. + +The results vary depending on the hardware, so you may have to try both +drivers. Use the option +[`services.xserver.videoDrivers`](options.html#opt-services.xserver.videoDrivers) +to set one. The recommended configuration for modern systems is: + +```nix +services.xserver.videoDrivers = [ "modesetting" ]; +services.xserver.useGlamor = true; +``` + +If you experience screen tearing no matter what, this configuration was +reported to resolve the issue: + +```nix +services.xserver.videoDrivers = [ "intel" ]; +services.xserver.deviceSection = '' + Option "DRI" "2" + Option "TearFree" "true" +''; +``` + +Note that this will likely downgrade the performance compared to +`modesetting` or `intel` with DRI 3 (default). + +## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered} + +NVIDIA provides a proprietary driver for its graphics cards that has +better 3D performance than the X.org drivers. It is not enabled by +default because it's not free software. You can enable it as follows: + +```nix +services.xserver.videoDrivers = [ "nvidia" ]; +``` + +Or if you have an older card, you may have to use one of the legacy +drivers: + +```nix +services.xserver.videoDrivers = [ "nvidiaLegacy390" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy340" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy304" ]; +``` + +You may need to reboot after enabling this driver to prevent a clash +with other kernel modules. + +## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered} + +AMD provides a proprietary driver for its graphics cards that is not +enabled by default because it's not Free Software, is often broken in +nixpkgs and as of this writing doesn\'t offer more features or +performance. If you still want to use it anyway, you need to explicitly +set: + +```nix +services.xserver.videoDrivers = [ "amdgpu-pro" ]; +``` + +You will need to reboot after enabling this driver to prevent a clash +with other kernel modules. + +## Touchpads {#sec-x11-touchpads .unnumbered} + +Support for Synaptics touchpads (found in many laptops such as the Dell +Latitude series) can be enabled as follows: + +```nix +services.xserver.libinput.enable = true; +``` + +The driver has many options (see [Appendix A, Configuration Options](options.html)). +For instance, the following disables tap-to-click behavior: + +```nix +services.xserver.libinput.touchpad.tapping = false; +``` + +Note: the use of `services.xserver.synaptics` is deprecated since NixOS +17.09. + +## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered} + +GTK themes can be installed either to user profile or system-wide (via +`environment.systemPackages`). To make Qt 5 applications look similar to +GTK ones, you can use the following configuration: + +```nix +qt5.enable = true; +qt5.platformTheme = "gtk2"; +qt5.style = "gtk2"; +``` + +## Custom XKB layouts {#custom-xkb-layouts .unnumbered} + +It is possible to install custom [ XKB +](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts +using the option `services.xserver.extraLayouts`. + +As a first example, we are going to create a layout based on the basic +US layout, with an additional layer to type some greek symbols by +pressing the right-alt key. + +Create a file called `us-greek` with the following content (under a +directory called `symbols`; it\'s an XKB peculiarity that will help with +testing): + +```nix +xkb_symbols "us-greek" +{ + include "us(basic)" // includes the base US keys + include "level3(ralt_switch)" // configures right alt as a third level switch + + key { [ a, A, Greek_alpha ] }; + key { [ b, B, Greek_beta ] }; + key { [ g, G, Greek_gamma ] }; + key { [ d, D, Greek_delta ] }; + key { [ z, Z, Greek_zeta ] }; +}; +``` + +A minimal layout specification must include the following: + +```nix +services.xserver.extraLayouts.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /yourpath/symbols/us-greek; +}; +``` + +::: {.note} +The name (after `extraLayouts.`) should match the one given to the +`xkb_symbols` block. +::: + +Applying this customization requires rebuilding several packages, and a +broken XKB file can lead to the X session crashing at login. Therefore, +you\'re strongly advised to **test your layout before applying it**: + +```ShellSession +$ nix-shell -p xorg.xkbcomp +$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY +``` + +You can inspect the predefined XKB files for examples: + +```ShellSession +$ echo "$(nix-build --no-out-link '' -A xorg.xkeyboardconfig)/etc/X11/xkb/" +``` + +Once the configuration is applied, and you did a logout/login cycle, the +layout should be ready to use. You can try it by e.g. running +`setxkbmap us-greek` and then type `+a` (it may not get applied in +your terminal straight away). To change the default, the usual +`services.xserver.layout` option can still be used. + +A layout can have several other components besides `xkb_symbols`, for +example we will define new keycodes for some multimedia key and bind +these to some symbol. + +Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys +of interest, then create a `media-key` file to hold the keycodes +definitions + +```nix +xkb_keycodes "media" +{ + = 123; + = 456; +} +``` + +Now use the newly define keycodes in `media-sym`: + +```nix +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key { [ XF86AudioLowerVolume ] }; + key { [ XF86AudioRaiseVolume ] }; +} +``` + +As before, to install the layout do + +```nix +services.xserver.extraLayouts.media = { + description = "Multimedia keys remapping"; + languages = [ "eng" ]; + symbolsFile = /path/to/media-key; + keycodesFile = /path/to/media-sym; +}; +``` + +::: {.note} +The function `pkgs.writeText ` can be useful if you +prefer to keep the layout definitions inside the NixOS configuration. +::: + +Unfortunately, the Xorg server does not (currently) support setting a +keymap directly but relies instead on XKB rules to select the matching +components (keycodes, types, \...) of a layout. This means that +components other than symbols won\'t be loaded by default. As a +workaround, you can set the keymap using `setxkbmap` at the start of the +session with: + +```nix +services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media"; +``` + +If you are manually starting the X server, you should set the argument +`-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For +example with `xinit` run + +```ShellSession +$ xinit -- -xkbdir /etc/X11/xkb +``` + +To learn how to write layouts take a look at the XKB [documentation +](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts). +More example layouts can also be found [here +](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples). diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml deleted file mode 100644 index f9121508d7d4..000000000000 --- a/nixos/doc/manual/configuration/x-windows.xml +++ /dev/null @@ -1,355 +0,0 @@ - - X Window System - - The X Window System (X11) provides the basis of NixOS’ graphical user - interface. It can be enabled as follows: - - = true; - - The X server will automatically detect and use the appropriate video driver - from a set of X.org drivers (such as vesa and - intel). You can also specify a driver manually, e.g. - - = [ "r128" ]; - - to enable X.org’s xf86-video-r128 driver. - - - You also need to enable at least one desktop or window manager. Otherwise, - you can only log into a plain undecorated xterm window. - Thus you should pick one or more of the following lines: - - = true; - = true; - = true; - = true; - = true; - = true; - = true; - = true; - = true; - - - - NixOS’s default display manager (the program that - provides a graphical login prompt and manages the X server) is LightDM. You - can select an alternative one by picking one of the following lines: - - = true; - = true; - - - - You can set the keyboard layout (and optionally the layout variant): - - = "de"; - = "neo"; - - - - The X server is started automatically at boot time. If you don’t want this - to happen, you can set: - - = false; - - The X server can then be started manually: - -# systemctl start display-manager.service - - - - On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine, - you should also set the following: - - = true; - - - - Auto-login - - The x11 login screen can be skipped entirely, automatically logging you into - your window manager and desktop environment when you boot your computer. - - - This is especially helpful if you have disk encryption enabled. Since you - already have to provide a password to decrypt your disk, entering a second - password to login can be redundant. - - - To enable auto-login, you need to define your default window manager and - desktop environment. If you wanted no desktop environment and i3 as your your - window manager, you'd define: - - = "none+i3"; - - Every display manager in NixOS supports auto-login, here is an example - using lightdm for a user alice: - - = true; - = true; - = "alice"; - - - - - Intel Graphics drivers - - There are two choices for Intel Graphics drivers in X.org: - modesetting (included in the xorg-server itself) - and intel (provided by the package xf86-video-intel). - - - The default and recommended is modesetting. - It is a generic driver which uses the kernel - mode setting - (KMS) mechanism. It supports Glamor (2D graphics acceleration via OpenGL) - and is actively maintained but may perform worse in some cases (like in old chipsets). - - - The second driver, intel, is specific to Intel GPUs, - but not recommended by most distributions: it lacks several modern features - (for example, it doesn't support Glamor) and the package hasn't been officially - updated since 2015. - - - The results vary depending on the hardware, so you may have to try both drivers. - Use the option to set one. - The recommended configuration for modern systems is: - - = [ "modesetting" ]; - = true; - - If you experience screen tearing no matter what, this configuration was - reported to resolve the issue: - - = [ "intel" ]; - = '' - Option "DRI" "2" - Option "TearFree" "true" - ''; - - Note that this will likely downgrade the performance compared to - modesetting or intel with DRI 3 (default). - - - - Proprietary NVIDIA drivers - - NVIDIA provides a proprietary driver for its graphics cards that has better - 3D performance than the X.org drivers. It is not enabled by default because - it’s not free software. You can enable it as follows: - - = [ "nvidia" ]; - - Or if you have an older card, you may have to use one of the legacy drivers: - - = [ "nvidiaLegacy390" ]; - = [ "nvidiaLegacy340" ]; - = [ "nvidiaLegacy304" ]; - - You may need to reboot after enabling this driver to prevent a clash with - other kernel modules. - - - - Proprietary AMD drivers - - AMD provides a proprietary driver for its graphics cards that is not - enabled by default because it’s not Free Software, is often broken - in nixpkgs and as of this writing doesn't offer more features or - performance. If you still want to use it anyway, you need to explicitly set: - - = [ "amdgpu-pro" ]; - - You will need to reboot after enabling this driver to prevent a clash with - other kernel modules. - - - - Touchpads - - Support for Synaptics touchpads (found in many laptops such as the Dell - Latitude series) can be enabled as follows: - - = true; - - The driver has many options (see ). For - instance, the following disables tap-to-click behavior: - - = false; - - Note: the use of services.xserver.synaptics is deprecated - since NixOS 17.09. - - - - GTK/Qt themes - - GTK themes can be installed either to user profile or system-wide (via - environment.systemPackages). To make Qt 5 applications - look similar to GTK ones, you can use the following configuration: - - = true; - = "gtk2"; - = "gtk2"; - - - - - Custom XKB layouts - - It is possible to install custom - - XKB - - keyboard layouts using the option - . - - - As a first example, we are going to create a layout based on the basic US - layout, with an additional layer to type some greek symbols by pressing the - right-alt key. - - - Create a file called us-greek with the following - content (under a directory called symbols; it's - an XKB peculiarity that will help with testing): - - -xkb_symbols "us-greek" -{ - include "us(basic)" // includes the base US keys - include "level3(ralt_switch)" // configures right alt as a third level switch - - key <LatA> { [ a, A, Greek_alpha ] }; - key <LatB> { [ b, B, Greek_beta ] }; - key <LatG> { [ g, G, Greek_gamma ] }; - key <LatD> { [ d, D, Greek_delta ] }; - key <LatZ> { [ z, Z, Greek_zeta ] }; -}; - - - A minimal layout specification must include the following: - - -.us-greek = { - description = "US layout with alt-gr greek"; - languages = [ "eng" ]; - symbolsFile = /yourpath/symbols/us-greek; -}; - - - - The name (after extraLayouts.) should match the one given to the - xkb_symbols block. - - - - Applying this customization requires rebuilding several packages, - and a broken XKB file can lead to the X session crashing at login. - Therefore, you're strongly advised to test - your layout before applying it: - -$ nix-shell -p xorg.xkbcomp -$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY - - - - You can inspect the predefined XKB files for examples: - -$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/" - - - - Once the configuration is applied, and you did a logout/login - cycle, the layout should be ready to use. You can try it by e.g. - running setxkbmap us-greek and then type - <alt>+a (it may not get applied in your - terminal straight away). To change the default, the usual - - option can still be used. - - - A layout can have several other components besides - xkb_symbols, for example we will define new - keycodes for some multimedia key and bind these to some symbol. - - - Use the xev utility from - pkgs.xorg.xev to find the codes of the keys of - interest, then create a media-key file to hold - the keycodes definitions - - -xkb_keycodes "media" -{ - <volUp> = 123; - <volDown> = 456; -} - - - Now use the newly define keycodes in media-sym: - - -xkb_symbols "media" -{ - key.type = "ONE_LEVEL"; - key <volUp> { [ XF86AudioLowerVolume ] }; - key <volDown> { [ XF86AudioRaiseVolume ] }; -} - - - As before, to install the layout do - - -.media = { - description = "Multimedia keys remapping"; - languages = [ "eng" ]; - symbolsFile = /path/to/media-key; - keycodesFile = /path/to/media-sym; -}; - - - - The function pkgs.writeText <filename> <content> - can be useful if you prefer to keep the layout definitions - inside the NixOS configuration. - - - - Unfortunately, the Xorg server does not (currently) support setting a - keymap directly but relies instead on XKB rules to select the matching - components (keycodes, types, ...) of a layout. This means that components - other than symbols won't be loaded by default. As a workaround, you - can set the keymap using setxkbmap at the start of the - session with: - - - = "setxkbmap -keycodes media"; - - - If you are manually starting the X server, you should set the argument - -xkbdir /etc/X11/xkb, otherwise X won't find your layout files. - For example with xinit run - $ xinit -- -xkbdir /etc/X11/xkb - - - To learn how to write layouts take a look at the XKB - - documentation - . More example layouts can also be found - - here - . - - - diff --git a/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml new file mode 100644 index 000000000000..8e67c66f1526 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml @@ -0,0 +1,383 @@ + + X Window System + + The X Window System (X11) provides the basis of NixOS’ graphical + user interface. It can be enabled as follows: + + +services.xserver.enable = true; + + + The X server will automatically detect and use the appropriate video + driver from a set of X.org drivers (such as vesa + and intel). You can also specify a driver + manually, e.g. + + +services.xserver.videoDrivers = [ "r128" ]; + + + to enable X.org’s xf86-video-r128 driver. + + + You also need to enable at least one desktop or window manager. + Otherwise, you can only log into a plain undecorated + xterm window. Thus you should pick one or more of + the following lines: + + +services.xserver.desktopManager.plasma5.enable = true; +services.xserver.desktopManager.xfce.enable = true; +services.xserver.desktopManager.gnome.enable = true; +services.xserver.desktopManager.mate.enable = true; +services.xserver.windowManager.xmonad.enable = true; +services.xserver.windowManager.twm.enable = true; +services.xserver.windowManager.icewm.enable = true; +services.xserver.windowManager.i3.enable = true; +services.xserver.windowManager.herbstluftwm.enable = true; + + + NixOS’s default display manager (the program + that provides a graphical login prompt and manages the X server) is + LightDM. You can select an alternative one by picking one of the + following lines: + + +services.xserver.displayManager.sddm.enable = true; +services.xserver.displayManager.gdm.enable = true; + + + You can set the keyboard layout (and optionally the layout variant): + + +services.xserver.layout = "de"; +services.xserver.xkbVariant = "neo"; + + + The X server is started automatically at boot time. If you don’t + want this to happen, you can set: + + +services.xserver.autorun = false; + + + The X server can then be started manually: + + +# systemctl start display-manager.service + + + On 64-bit systems, if you want OpenGL for 32-bit programs such as in + Wine, you should also set the following: + + +hardware.opengl.driSupport32Bit = true; + +
+ Auto-login + + The x11 login screen can be skipped entirely, automatically + logging you into your window manager and desktop environment when + you boot your computer. + + + This is especially helpful if you have disk encryption enabled. + Since you already have to provide a password to decrypt your disk, + entering a second password to login can be redundant. + + + To enable auto-login, you need to define your default window + manager and desktop environment. If you wanted no desktop + environment and i3 as your your window manager, you'd define: + + +services.xserver.displayManager.defaultSession = "none+i3"; + + + Every display manager in NixOS supports auto-login, here is an + example using lightdm for a user alice: + + +services.xserver.displayManager.lightdm.enable = true; +services.xserver.displayManager.autoLogin.enable = true; +services.xserver.displayManager.autoLogin.user = "alice"; + +
+
+ Intel Graphics drivers + + There are two choices for Intel Graphics drivers in X.org: + modesetting (included in the xorg-server + itself) and intel (provided by the package + xf86-video-intel). + + + The default and recommended is modesetting. It + is a generic driver which uses the kernel + mode + setting (KMS) mechanism. It supports Glamor (2D graphics + acceleration via OpenGL) and is actively maintained but may + perform worse in some cases (like in old chipsets). + + + The second driver, intel, is specific to Intel + GPUs, but not recommended by most distributions: it lacks several + modern features (for example, it doesn't support Glamor) and the + package hasn't been officially updated since 2015. + + + The results vary depending on the hardware, so you may have to try + both drivers. Use the option + services.xserver.videoDrivers + to set one. The recommended configuration for modern systems is: + + +services.xserver.videoDrivers = [ "modesetting" ]; +services.xserver.useGlamor = true; + + + If you experience screen tearing no matter what, this + configuration was reported to resolve the issue: + + +services.xserver.videoDrivers = [ "intel" ]; +services.xserver.deviceSection = '' + Option "DRI" "2" + Option "TearFree" "true" +''; + + + Note that this will likely downgrade the performance compared to + modesetting or intel with + DRI 3 (default). + +
+
+ Proprietary NVIDIA drivers + + NVIDIA provides a proprietary driver for its graphics cards that + has better 3D performance than the X.org drivers. It is not + enabled by default because it’s not free software. You can enable + it as follows: + + +services.xserver.videoDrivers = [ "nvidia" ]; + + + Or if you have an older card, you may have to use one of the + legacy drivers: + + +services.xserver.videoDrivers = [ "nvidiaLegacy390" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy340" ]; +services.xserver.videoDrivers = [ "nvidiaLegacy304" ]; + + + You may need to reboot after enabling this driver to prevent a + clash with other kernel modules. + +
+
+ Proprietary AMD drivers + + AMD provides a proprietary driver for its graphics cards that is + not enabled by default because it’s not Free Software, is often + broken in nixpkgs and as of this writing doesn't offer more + features or performance. If you still want to use it anyway, you + need to explicitly set: + + +services.xserver.videoDrivers = [ "amdgpu-pro" ]; + + + You will need to reboot after enabling this driver to prevent a + clash with other kernel modules. + +
+
+ Touchpads + + Support for Synaptics touchpads (found in many laptops such as the + Dell Latitude series) can be enabled as follows: + + +services.xserver.libinput.enable = true; + + + The driver has many options (see + Appendix A, Configuration + Options). For instance, the following disables tap-to-click + behavior: + + +services.xserver.libinput.touchpad.tapping = false; + + + Note: the use of services.xserver.synaptics is + deprecated since NixOS 17.09. + +
+
+ GTK/Qt themes + + GTK themes can be installed either to user profile or system-wide + (via environment.systemPackages). To make Qt 5 + applications look similar to GTK ones, you can use the following + configuration: + + +qt5.enable = true; +qt5.platformTheme = "gtk2"; +qt5.style = "gtk2"; + +
+
+ Custom XKB layouts + + It is possible to install custom + + XKB keyboard layouts using the option + services.xserver.extraLayouts. + + + As a first example, we are going to create a layout based on the + basic US layout, with an additional layer to type some greek + symbols by pressing the right-alt key. + + + Create a file called us-greek with the + following content (under a directory called + symbols; it's an XKB peculiarity that will help + with testing): + + +xkb_symbols "us-greek" +{ + include "us(basic)" // includes the base US keys + include "level3(ralt_switch)" // configures right alt as a third level switch + + key <LatA> { [ a, A, Greek_alpha ] }; + key <LatB> { [ b, B, Greek_beta ] }; + key <LatG> { [ g, G, Greek_gamma ] }; + key <LatD> { [ d, D, Greek_delta ] }; + key <LatZ> { [ z, Z, Greek_zeta ] }; +}; + + + A minimal layout specification must include the following: + + +services.xserver.extraLayouts.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /yourpath/symbols/us-greek; +}; + + + + The name (after extraLayouts.) should match + the one given to the xkb_symbols block. + + + + Applying this customization requires rebuilding several packages, + and a broken XKB file can lead to the X session crashing at login. + Therefore, you're strongly advised to test + your layout before applying it: + + +$ nix-shell -p xorg.xkbcomp +$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY + + + You can inspect the predefined XKB files for examples: + + +$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/" + + + Once the configuration is applied, and you did a logout/login + cycle, the layout should be ready to use. You can try it by e.g. + running setxkbmap us-greek and then type + <alt>+a (it may not get applied in your + terminal straight away). To change the default, the usual + services.xserver.layout option can still be + used. + + + A layout can have several other components besides + xkb_symbols, for example we will define new + keycodes for some multimedia key and bind these to some symbol. + + + Use the xev utility from + pkgs.xorg.xev to find the codes of the keys of + interest, then create a media-key file to hold + the keycodes definitions + + +xkb_keycodes "media" +{ + <volUp> = 123; + <volDown> = 456; +} + + + Now use the newly define keycodes in media-sym: + + +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} + + + As before, to install the layout do + + +services.xserver.extraLayouts.media = { + description = "Multimedia keys remapping"; + languages = [ "eng" ]; + symbolsFile = /path/to/media-key; + keycodesFile = /path/to/media-sym; +}; + + + + The function + pkgs.writeText <filename> <content> + can be useful if you prefer to keep the layout definitions + inside the NixOS configuration. + + + + Unfortunately, the Xorg server does not (currently) support + setting a keymap directly but relies instead on XKB rules to + select the matching components (keycodes, types, ...) of a layout. + This means that components other than symbols won't be loaded by + default. As a workaround, you can set the keymap using + setxkbmap at the start of the session with: + + +services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media"; + + + If you are manually starting the X server, you should set the + argument -xkbdir /etc/X11/xkb, otherwise X + won't find your layout files. For example with + xinit run + + +$ xinit -- -xkbdir /etc/X11/xkb + + + To learn how to write layouts take a look at the XKB + documentation + . More example layouts can also be found + here + . + +
+ From f04b9023e36c290f41446240c55e1407ac8e0c9e Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:38:06 +0800 Subject: [PATCH 03/10] nixos: nixos/doc/manual/configuration/wayland.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../manual/configuration/wayland.chapter.md | 27 +++++++++++++++ nixos/doc/manual/configuration/wayland.xml | 33 ------------------- .../from_md/configuration/wayland.chapter.xml | 32 ++++++++++++++++++ 4 files changed, 60 insertions(+), 34 deletions(-) create mode 100644 nixos/doc/manual/configuration/wayland.chapter.md delete mode 100644 nixos/doc/manual/configuration/wayland.xml create mode 100644 nixos/doc/manual/from_md/configuration/wayland.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 4598ae4d1399..adc3a88b3d8f 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -18,7 +18,7 @@ - + diff --git a/nixos/doc/manual/configuration/wayland.chapter.md b/nixos/doc/manual/configuration/wayland.chapter.md new file mode 100644 index 000000000000..49c0cab38e5e --- /dev/null +++ b/nixos/doc/manual/configuration/wayland.chapter.md @@ -0,0 +1,27 @@ +# Wayland {#sec-wayland} + +While X11 (see [](#sec-x11)) is still the primary display technology +on NixOS, Wayland support is steadily improving. Where X11 separates the +X Server and the window manager, on Wayland those are combined: a +Wayland Compositor is like an X11 window manager, but also embeds the +Wayland \'Server\' functionality. This means it is sufficient to install +a Wayland Compositor such as sway without separately enabling a Wayland +server: + +```nix +programs.sway.enable = true; +``` + +This installs the sway compositor along with some essential utilities. +Now you can start sway from the TTY console. + +If you are using a wlroots-based compositor, like sway, and want to be +able to share your screen, you might want to activate this option: + +```nix +xdg.portal.wlr.enable = true; +``` + +and configure Pipewire using +[`services.pipewire.enable`](options.html#opt-services.pipewire.enable) +and related options. diff --git a/nixos/doc/manual/configuration/wayland.xml b/nixos/doc/manual/configuration/wayland.xml deleted file mode 100644 index 2aefda3e22c0..000000000000 --- a/nixos/doc/manual/configuration/wayland.xml +++ /dev/null @@ -1,33 +0,0 @@ - - Wayland - - - While X11 (see ) is still the primary display - technology on NixOS, Wayland support is steadily improving. - Where X11 separates the X Server and the window manager, on Wayland those - are combined: a Wayland Compositor is like an X11 window manager, but also - embeds the Wayland 'Server' functionality. This means it is sufficient to - install a Wayland Compositor such as sway without - separately enabling a Wayland server: - - = true; - - This installs the sway compositor along with some - essential utilities. Now you can start sway from the TTY - console. - - - - If you are using a wlroots-based compositor, like sway, and want to be able to - share your screen, you might want to activate this option: - - = true; - - and configure Pipewire using - and related options. - - diff --git a/nixos/doc/manual/from_md/configuration/wayland.chapter.xml b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml new file mode 100644 index 000000000000..166925f67d22 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml @@ -0,0 +1,32 @@ + + Wayland + + While X11 (see ) is still the primary + display technology on NixOS, Wayland support is steadily improving. + Where X11 separates the X Server and the window manager, on Wayland + those are combined: a Wayland Compositor is like an X11 window + manager, but also embeds the Wayland 'Server' functionality. This + means it is sufficient to install a Wayland Compositor such as sway + without separately enabling a Wayland server: + + +programs.sway.enable = true; + + + This installs the sway compositor along with some essential + utilities. Now you can start sway from the TTY console. + + + If you are using a wlroots-based compositor, like sway, and want to + be able to share your screen, you might want to activate this + option: + + +xdg.portal.wlr.enable = true; + + + and configure Pipewire using + services.pipewire.enable + and related options. + + From 5ad28f419704436d1eaa0e82295f15c556fa5dce Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:38:53 +0800 Subject: [PATCH 04/10] nixos: nixos/doc/manual/configuration/gpu-accel.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../manual/configuration/gpu-accel.chapter.md | 204 ++++++++++++++ nixos/doc/manual/configuration/gpu-accel.xml | 262 ------------------ .../configuration/gpu-accel.chapter.xml | 244 ++++++++++++++++ 4 files changed, 449 insertions(+), 263 deletions(-) create mode 100644 nixos/doc/manual/configuration/gpu-accel.chapter.md delete mode 100644 nixos/doc/manual/configuration/gpu-accel.xml create mode 100644 nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index adc3a88b3d8f..b24399a2f2aa 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -19,7 +19,7 @@ - + diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md new file mode 100644 index 000000000000..5540250e1da7 --- /dev/null +++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md @@ -0,0 +1,204 @@ +# GPU acceleration {#sec-gpu-accel} + +NixOS provides various APIs that benefit from GPU hardware acceleration, +such as VA-API and VDPAU for video playback; OpenGL and Vulkan for 3D +graphics; and OpenCL for general-purpose computing. This chapter +describes how to set up GPU hardware acceleration (as far as this is not +done automatically) and how to verify that hardware acceleration is +indeed used. + +Most of the aforementioned APIs are agnostic with regards to which +display server is used. Consequently, these instructions should apply +both to the X Window System and Wayland compositors. + +## OpenCL {#sec-gpu-accel-opencl} + +[OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API. +It is used by various applications such as Blender and Darktable to +accelerate certain operations. + +OpenCL applications load drivers through the *Installable Client Driver* +(ICD) mechanism. In this mechanism, an ICD file specifies the path to +the OpenCL driver for a particular GPU family. In NixOS, there are two +ways to make ICD files visible to the ICD loader. The first is through +the `OCL_ICD_VENDORS` environment variable. This variable can contain a +directory which is scanned by the ICL loader for ICD files. For example: + +```ShellSession +$ export \ + OCL_ICD_VENDORS=`nix-build '' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/ +``` + +The second mechanism is to add the OpenCL driver package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages). +This links the ICD file under `/run/opengl-driver`, where it will be visible +to the ICD loader. + +The proper installation of OpenCL drivers can be verified through the +`clinfo` command of the clinfo package. This command will report the +number of hardware devices that is found and give detailed information +for each device: + +```ShellSession +$ clinfo | head -n3 +Number of platforms 1 +Platform Name AMD Accelerated Parallel Processing +Platform Vendor Advanced Micro Devices, Inc. +``` + +### AMD {#sec-gpu-accel-opencl-amd} + +Modern AMD [Graphics Core +Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are +supported through the rocm-opencl-icd package. Adding this package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +enables OpenCL support: + +```nix +hardware.opengl.extraPackages = [ + rocm-opencl-icd + ]; +``` + +### Intel {#sec-gpu-accel-opencl-intel} + +[Intel Gen8 and later +GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8) +are supported by the Intel NEO OpenCL runtime that is provided by the +intel-compute-runtime package. For Gen7 GPUs, the deprecated Beignet +runtime can be used, which is provided by the beignet package. The +proprietary Intel OpenCL runtime, in the intel-ocl package, is an +alternative for Gen7 GPUs. + +The intel-compute-runtime, beignet, or intel-ocl package can be added to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +to enable OpenCL support. For example, for Gen8 and later GPUs, the following +configuration can be used: + +```nix +hardware.opengl.extraPackages = [ + intel-compute-runtime + ]; +``` + +## Vulkan {#sec-gpu-accel-vulkan} + +[Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and +compute API for GPUs. It is used directly by games or indirectly though +compatibility layers like +[DXVK](https://github.com/doitsujin/dxvk/wiki). + +By default, if [`hardware.opengl.driSupport`](options.html#opt-hardware.opengl.driSupport) +is enabled, mesa is installed and provides Vulkan for supported hardware. + +Similar to OpenCL, Vulkan drivers are loaded through the *Installable +Client Driver* (ICD) mechanism. ICD files for Vulkan are JSON files that +specify the path to the driver library and the supported Vulkan version. +All successfully loaded drivers are exposed to the application as +different GPUs. In NixOS, there are two ways to make ICD files visible +to Vulkan applications: an environment variable and a module option. + +The first option is through the `VK_ICD_FILENAMES` environment variable. +This variable can contain multiple JSON files, separated by `:`. For +example: + +```ShellSession +$ export \ + VK_ICD_FILENAMES=`nix-build '' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json +``` + +The second mechanism is to add the Vulkan driver package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages). +This links the ICD file under `/run/opengl-driver`, where it will be +visible to the ICD loader. + +The proper installation of Vulkan drivers can be verified through the +`vulkaninfo` command of the vulkan-tools package. This command will +report the hardware devices and drivers found, in this example output +amdvlk and radv: + +```ShellSession +$ vulkaninfo | grep GPU + GPU id : 0 (Unknown AMD GPU) + GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1)) + ... +GPU0: + deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU + deviceName = Unknown AMD GPU +GPU1: + deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU +``` + +A simple graphical application that uses Vulkan is `vkcube` from the +vulkan-tools package. + +### AMD {#sec-gpu-accel-vulkan-amd} + +Modern AMD [Graphics Core +Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are +supported through either radv, which is part of mesa, or the amdvlk +package. Adding the amdvlk package to +[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +makes amdvlk the default driver and hides radv and lavapipe from the device list. +A specific driver can be forced as follows: + +```nix +hardware.opengl.extraPackages = [ + pkgs.amdvlk + ]; + + # To enable Vulkan support for 32-bit applications, also add: + hardware.opengl.extraPackages32 = [ + pkgs.driversi686Linux.amdvlk + ]; + + # Force radv + environment.variables.AMD_VULKAN_ICD = "RADV"; + # Or + environment.variables.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; +``` + +## Common issues {#sec-gpu-accel-common-issues} + +### User permissions {#sec-gpu-accel-common-issues-permissions} + +Except where noted explicitly, it should not be necessary to adjust user +permissions to use these acceleration APIs. In the default +configuration, GPU devices have world-read/write permissions +(`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The +access control lists of devices with the `uaccess` tag will be updated +automatically when a user logs in through `systemd-logind`. For example, +if the user *jane* is logged in, the access control list should look as +follows: + +```ShellSession +$ getfacl /dev/dri/card0 +# file: dev/dri/card0 +# owner: root +# group: video +user::rw- +user:jane:rw- +group::rw- +mask::rw- +other::--- +``` + +If you disabled (this functionality of) `systemd-logind`, you may need +to add the user to the `video` group and log in again. + +### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs} + +The *Installable Client Driver* (ICD) mechanism used by OpenCL and +Vulkan loads runtimes into its address space using `dlopen`. Mixing an +ICD loader mechanism and runtimes from different version of nixpkgs may +not work. For example, if the ICD loader uses an older version of glibc +than the runtime, the runtime may not be loadable due to missing +symbols. Unfortunately, the loader will generally be quiet about such +issues. + +If you suspect that you are running into library version mismatches +between an ICL loader and a runtime, you could run an application with +the `LD_DEBUG` variable set to get more diagnostic information. For +example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should +report missing symbols. diff --git a/nixos/doc/manual/configuration/gpu-accel.xml b/nixos/doc/manual/configuration/gpu-accel.xml deleted file mode 100644 index 9aa9be86a061..000000000000 --- a/nixos/doc/manual/configuration/gpu-accel.xml +++ /dev/null @@ -1,262 +0,0 @@ - - GPU acceleration - - - NixOS provides various APIs that benefit from GPU hardware - acceleration, such as VA-API and VDPAU for video playback; OpenGL and - Vulkan for 3D graphics; and OpenCL for general-purpose computing. - This chapter describes how to set up GPU hardware acceleration (as far - as this is not done automatically) and how to verify that hardware - acceleration is indeed used. - - - - Most of the aforementioned APIs are agnostic with regards to which - display server is used. Consequently, these instructions should apply - both to the X Window System and Wayland compositors. - - -
- OpenCL - - - OpenCL is a - general compute API. It is used by various applications such as - Blender and Darktable to accelerate certain operations. - - - - OpenCL applications load drivers through the Installable Client - Driver (ICD) mechanism. In this mechanism, an ICD file - specifies the path to the OpenCL driver for a particular GPU family. - In NixOS, there are two ways to make ICD files visible to the ICD - loader. The first is through the OCL_ICD_VENDORS - environment variable. This variable can contain a directory which - is scanned by the ICL loader for ICD files. For example: - - $ export \ - OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/ - - - - The second mechanism is to add the OpenCL driver package to - . This links the - ICD file under /run/opengl-driver, where it will - be visible to the ICD loader. - - - - The proper installation of OpenCL drivers can be verified through - the clinfo command of the clinfo - package. This command will report the number of hardware devices - that is found and give detailed information for each device: - - - $ clinfo | head -n3 -Number of platforms 1 -Platform Name AMD Accelerated Parallel Processing -Platform Vendor Advanced Micro Devices, Inc. - -
- AMD - - - Modern AMD Graphics - Core Next (GCN) GPUs are supported through the - rocm-opencl-icd package. Adding this package to - enables OpenCL - support: - - = [ - rocm-opencl-icd - ]; - -
- -
- Intel - - - Intel - Gen8 and later GPUs are supported by the Intel NEO OpenCL - runtime that is provided by the - intel-compute-runtime package. For Gen7 GPUs, - the deprecated Beignet runtime can be used, which is provided - by the beignet package. The proprietary Intel - OpenCL runtime, in the intel-ocl package, is - an alternative for Gen7 GPUs. - - - - The intel-compute-runtime, beignet, - or intel-ocl package can be added to - to enable OpenCL - support. For example, for Gen8 and later GPUs, the following - configuration can be used: - - = [ - intel-compute-runtime - ]; - - -
-
- -
- Vulkan - - - Vulkan is a - graphics and compute API for GPUs. It is used directly by games or indirectly though - compatibility layers like DXVK. - - - - By default, if is enabled, - mesa is installed and provides Vulkan for supported hardware. - - - - Similar to OpenCL, Vulkan drivers are loaded through the Installable Client - Driver (ICD) mechanism. ICD files for Vulkan are JSON files that specify - the path to the driver library and the supported Vulkan version. All successfully - loaded drivers are exposed to the application as different GPUs. - In NixOS, there are two ways to make ICD files visible to Vulkan applications: an - environment variable and a module option. - - - - The first option is through the VK_ICD_FILENAMES - environment variable. This variable can contain multiple JSON files, separated by - :. For example: - - $ export \ - VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json - - - - The second mechanism is to add the Vulkan driver package to - . This links the - ICD file under /run/opengl-driver, where it will - be visible to the ICD loader. - - - - The proper installation of Vulkan drivers can be verified through - the vulkaninfo command of the vulkan-tools - package. This command will report the hardware devices and drivers found, - in this example output amdvlk and radv: - - - $ vulkaninfo | grep GPU - GPU id : 0 (Unknown AMD GPU) - GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1)) - ... -GPU0: - deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - deviceName = Unknown AMD GPU -GPU1: - deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - - - A simple graphical application that uses Vulkan is vkcube - from the vulkan-tools package. - - -
- AMD - - - Modern AMD Graphics - Core Next (GCN) GPUs are supported through either radv, which is - part of mesa, or the amdvlk package. - Adding the amdvlk package to - makes amdvlk the - default driver and hides radv and lavapipe from the device list. A - specific driver can be forced as follows: - - = [ - pkgs.amdvlk - ]; - - # To enable Vulkan support for 32-bit applications, also add: - = [ - pkgs.driversi686Linux.amdvlk - ]; - - # Force radv - .AMD_VULKAN_ICD = "RADV"; - # Or - .VK_ICD_FILENAMES = - "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; - - -
-
- -
- Common issues - -
- User permissions - - - Except where noted explicitly, it should not be necessary to - adjust user permissions to use these acceleration APIs. In the default - configuration, GPU devices have world-read/write permissions - (/dev/dri/renderD*) or are tagged as - uaccess (/dev/dri/card*). The - access control lists of devices with the uaccess - tag will be updated automatically when a user logs in through - systemd-logind. For example, if the user - jane is logged in, the access control list - should look as follows: - - $ getfacl /dev/dri/card0 -# file: dev/dri/card0 -# owner: root -# group: video -user::rw- -user:jane:rw- -group::rw- -mask::rw- -other::--- - - If you disabled (this functionality of) systemd-logind, - you may need to add the user to the video group and - log in again. - -
- -
- Mixing different versions of nixpkgs - - - The Installable Client Driver (ICD) - mechanism used by OpenCL and Vulkan loads runtimes into its address - space using dlopen. Mixing an ICD loader mechanism and - runtimes from different version of nixpkgs may not work. For example, - if the ICD loader uses an older version of glibc - than the runtime, the runtime may not be loadable due to - missing symbols. Unfortunately, the loader will generally be quiet - about such issues. - - - - If you suspect that you are running into library version mismatches - between an ICL loader and a runtime, you could run an application with - the LD_DEBUG variable set to get more diagnostic - information. For example, OpenCL can be tested with - LD_DEBUG=files clinfo, which should report missing - symbols. - -
-
- diff --git a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml new file mode 100644 index 000000000000..ec6468101849 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml @@ -0,0 +1,244 @@ + + GPU acceleration + + NixOS provides various APIs that benefit from GPU hardware + acceleration, such as VA-API and VDPAU for video playback; OpenGL + and Vulkan for 3D graphics; and OpenCL for general-purpose + computing. This chapter describes how to set up GPU hardware + acceleration (as far as this is not done automatically) and how to + verify that hardware acceleration is indeed used. + + + Most of the aforementioned APIs are agnostic with regards to which + display server is used. Consequently, these instructions should + apply both to the X Window System and Wayland compositors. + +
+ OpenCL + + OpenCL + is a general compute API. It is used by various applications such + as Blender and Darktable to accelerate certain operations. + + + OpenCL applications load drivers through the Installable + Client Driver (ICD) mechanism. In this mechanism, an + ICD file specifies the path to the OpenCL driver for a particular + GPU family. In NixOS, there are two ways to make ICD files visible + to the ICD loader. The first is through the + OCL_ICD_VENDORS environment variable. This + variable can contain a directory which is scanned by the ICL + loader for ICD files. For example: + + +$ export \ + OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/ + + + The second mechanism is to add the OpenCL driver package to + hardware.opengl.extraPackages. + This links the ICD file under + /run/opengl-driver, where it will be visible to + the ICD loader. + + + The proper installation of OpenCL drivers can be verified through + the clinfo command of the clinfo package. This + command will report the number of hardware devices that is found + and give detailed information for each device: + + +$ clinfo | head -n3 +Number of platforms 1 +Platform Name AMD Accelerated Parallel Processing +Platform Vendor Advanced Micro Devices, Inc. + +
+ AMD + + Modern AMD + Graphics + Core Next (GCN) GPUs are supported through the + rocm-opencl-icd package. Adding this package to + hardware.opengl.extraPackages + enables OpenCL support: + + +hardware.opengl.extraPackages = [ + rocm-opencl-icd + ]; + +
+
+ Intel + + Intel + Gen8 and later GPUs are supported by the Intel NEO OpenCL + runtime that is provided by the intel-compute-runtime package. + For Gen7 GPUs, the deprecated Beignet runtime can be used, which + is provided by the beignet package. The proprietary Intel OpenCL + runtime, in the intel-ocl package, is an alternative for Gen7 + GPUs. + + + The intel-compute-runtime, beignet, or intel-ocl package can be + added to + hardware.opengl.extraPackages + to enable OpenCL support. For example, for Gen8 and later GPUs, + the following configuration can be used: + + +hardware.opengl.extraPackages = [ + intel-compute-runtime + ]; + +
+
+
+ Vulkan + + Vulkan + is a graphics and compute API for GPUs. It is used directly by + games or indirectly though compatibility layers like + DXVK. + + + By default, if + hardware.opengl.driSupport + is enabled, mesa is installed and provides Vulkan for supported + hardware. + + + Similar to OpenCL, Vulkan drivers are loaded through the + Installable Client Driver (ICD) mechanism. + ICD files for Vulkan are JSON files that specify the path to the + driver library and the supported Vulkan version. All successfully + loaded drivers are exposed to the application as different GPUs. + In NixOS, there are two ways to make ICD files visible to Vulkan + applications: an environment variable and a module option. + + + The first option is through the + VK_ICD_FILENAMES environment variable. This + variable can contain multiple JSON files, separated by + :. For example: + + +$ export \ + VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json + + + The second mechanism is to add the Vulkan driver package to + hardware.opengl.extraPackages. + This links the ICD file under + /run/opengl-driver, where it will be visible to + the ICD loader. + + + The proper installation of Vulkan drivers can be verified through + the vulkaninfo command of the vulkan-tools + package. This command will report the hardware devices and drivers + found, in this example output amdvlk and radv: + + +$ vulkaninfo | grep GPU + GPU id : 0 (Unknown AMD GPU) + GPU id : 1 (AMD RADV NAVI10 (LLVM 9.0.1)) + ... +GPU0: + deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU + deviceName = Unknown AMD GPU +GPU1: + deviceType = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU + + + A simple graphical application that uses Vulkan is + vkcube from the vulkan-tools package. + +
+ AMD + + Modern AMD + Graphics + Core Next (GCN) GPUs are supported through either radv, + which is part of mesa, or the amdvlk package. Adding the amdvlk + package to + hardware.opengl.extraPackages + makes amdvlk the default driver and hides radv and lavapipe from + the device list. A specific driver can be forced as follows: + + +hardware.opengl.extraPackages = [ + pkgs.amdvlk + ]; + + # To enable Vulkan support for 32-bit applications, also add: + hardware.opengl.extraPackages32 = [ + pkgs.driversi686Linux.amdvlk + ]; + + # Force radv + environment.variables.AMD_VULKAN_ICD = "RADV"; + # Or + environment.variables.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; + +
+
+
+ Common issues +
+ User permissions + + Except where noted explicitly, it should not be necessary to + adjust user permissions to use these acceleration APIs. In the + default configuration, GPU devices have world-read/write + permissions (/dev/dri/renderD*) or are tagged + as uaccess + (/dev/dri/card*). The access control lists of + devices with the uaccess tag will be updated + automatically when a user logs in through + systemd-logind. For example, if the user + jane is logged in, the access control list + should look as follows: + + +$ getfacl /dev/dri/card0 +# file: dev/dri/card0 +# owner: root +# group: video +user::rw- +user:jane:rw- +group::rw- +mask::rw- +other::--- + + + If you disabled (this functionality of) + systemd-logind, you may need to add the user + to the video group and log in again. + +
+
+ Mixing different versions of nixpkgs + + The Installable Client Driver (ICD) + mechanism used by OpenCL and Vulkan loads runtimes into its + address space using dlopen. Mixing an ICD + loader mechanism and runtimes from different version of nixpkgs + may not work. For example, if the ICD loader uses an older + version of glibc than the runtime, the runtime may not be + loadable due to missing symbols. Unfortunately, the loader will + generally be quiet about such issues. + + + If you suspect that you are running into library version + mismatches between an ICL loader and a runtime, you could run an + application with the LD_DEBUG variable set to + get more diagnostic information. For example, OpenCL can be + tested with LD_DEBUG=files clinfo, which + should report missing symbols. + +
+
+ From 35f476e8b99cfeca7660665763bfbd1fb179498a Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:39:37 +0800 Subject: [PATCH 05/10] nixos: nixos/doc/manual/configuration/xfce.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../doc/manual/configuration/xfce.chapter.md | 52 ++++++++++++++++ nixos/doc/manual/configuration/xfce.xml | 59 ------------------ .../from_md/configuration/xfce.chapter.xml | 62 +++++++++++++++++++ 4 files changed, 115 insertions(+), 60 deletions(-) create mode 100644 nixos/doc/manual/configuration/xfce.chapter.md delete mode 100644 nixos/doc/manual/configuration/xfce.xml create mode 100644 nixos/doc/manual/from_md/configuration/xfce.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index b24399a2f2aa..cd56ac774d09 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -20,7 +20,7 @@ - + diff --git a/nixos/doc/manual/configuration/xfce.chapter.md b/nixos/doc/manual/configuration/xfce.chapter.md new file mode 100644 index 000000000000..3c0c5f3a6f38 --- /dev/null +++ b/nixos/doc/manual/configuration/xfce.chapter.md @@ -0,0 +1,52 @@ +# Xfce Desktop Environment {#sec-xfce} + +To enable the Xfce Desktop Environment, set + +```nix +services.xserver.desktopManager.xfce.enable = true; +services.xserver.displayManager.defaultSession = "xfce"; +``` + +Optionally, *picom* can be enabled for nice graphical effects, some +example settings: + +```nix +services.picom = { + enable = true; + fade = true; + inactiveOpacity = 0.9; + shadow = true; + fadeDelta = 4; +}; +``` + +Some Xfce programs are not installed automatically. To install them +manually (system wide), put them into your +[`environment.systemPackages`](options.html#opt-environment.systemPackages) from `pkgs.xfce`. + +## Thunar Plugins {#sec-xfce-thunar-plugins .unnumbered} + +If you\'d like to add extra plugins to Thunar, add them to +[`services.xserver.desktopManager.xfce.thunarPlugins`](options.html#opt-services.xserver.desktopManager.xfce.thunarPlugins). +You shouldn\'t just add them to [`environment.systemPackages`](options.html#opt-environment.systemPackages). + +## Troubleshooting {#sec-xfce-troubleshooting .unnumbered} + +Even after enabling udisks2, volume management might not work. Thunar +and/or the desktop takes time to show up. Thunar will spit out this kind +of message on start (look at `journalctl --user -b`). + +```plain +Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported +``` + +This is caused by some needed GNOME services not running. This is all +fixed by enabling \"Launch GNOME services on startup\" in the Advanced +tab of the Session and Startup settings panel. Alternatively, you can +run this command to do the same thing. + +```ShellSession +$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true +``` + +A log-out and re-log will be needed for this to take effect. diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml deleted file mode 100644 index abcf5f648a48..000000000000 --- a/nixos/doc/manual/configuration/xfce.xml +++ /dev/null @@ -1,59 +0,0 @@ - - Xfce Desktop Environment - - To enable the Xfce Desktop Environment, set - - = true; - = "xfce"; - - - - Optionally, picom can be enabled for nice graphical - effects, some example settings: - -services.picom = { - enable = true; - fade = true; - inactiveOpacity = 0.9; - shadow = true; - fadeDelta = 4; -}; - - - - Some Xfce programs are not installed automatically. To install them manually - (system wide), put them into your - from pkgs.xfce. - - - Thunar Plugins - - If you'd like to add extra plugins to Thunar, add them to - . - You shouldn't just add them to . - - - - Troubleshooting - - Even after enabling udisks2, volume management might not work. Thunar and/or - the desktop takes time to show up. Thunar will spit out this kind of message - on start (look at journalctl --user -b). - -Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported - - This is caused by some needed GNOME services not running. This is all fixed - by enabling "Launch GNOME services on startup" in the Advanced tab of the - Session and Startup settings panel. Alternatively, you can run this command - to do the same thing. - -$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true - - A log-out and re-log will be needed for this to take effect. - - - diff --git a/nixos/doc/manual/from_md/configuration/xfce.chapter.xml b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml new file mode 100644 index 000000000000..0066baa2dc70 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml @@ -0,0 +1,62 @@ + + Xfce Desktop Environment + + To enable the Xfce Desktop Environment, set + + +services.xserver.desktopManager.xfce.enable = true; +services.xserver.displayManager.defaultSession = "xfce"; + + + Optionally, picom can be enabled for nice + graphical effects, some example settings: + + +services.picom = { + enable = true; + fade = true; + inactiveOpacity = 0.9; + shadow = true; + fadeDelta = 4; +}; + + + Some Xfce programs are not installed automatically. To install them + manually (system wide), put them into your + environment.systemPackages + from pkgs.xfce. + +
+ Thunar Plugins + + If you'd like to add extra plugins to Thunar, add them to + services.xserver.desktopManager.xfce.thunarPlugins. + You shouldn't just add them to + environment.systemPackages. + +
+
+ Troubleshooting + + Even after enabling udisks2, volume management might not work. + Thunar and/or the desktop takes time to show up. Thunar will spit + out this kind of message on start (look at + journalctl --user -b). + + +Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported + + + This is caused by some needed GNOME services not running. This is + all fixed by enabling "Launch GNOME services on startup" + in the Advanced tab of the Session and Startup settings panel. + Alternatively, you can run this command to do the same thing. + + +$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true + + + A log-out and re-log will be needed for this to take effect. + +
+ From 747c61066c5e204d4523177e7b49d143dfd4ed52 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:40:22 +0800 Subject: [PATCH 06/10] nixos: nixos/doc/manual/configuration/linux-kernel.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../configuration/linux-kernel.chapter.md | 135 ++++++++++++++++ .../doc/manual/configuration/linux-kernel.xml | 138 ---------------- .../configuration/linux-kernel.chapter.xml | 153 ++++++++++++++++++ 4 files changed, 289 insertions(+), 139 deletions(-) create mode 100644 nixos/doc/manual/configuration/linux-kernel.chapter.md delete mode 100644 nixos/doc/manual/configuration/linux-kernel.xml create mode 100644 nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index cd56ac774d09..56574680f9c3 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -22,7 +22,7 @@ - + diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md new file mode 100644 index 000000000000..95af16663891 --- /dev/null +++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md @@ -0,0 +1,135 @@ +# Linux Kernel {#sec-kernel-config} + +You can override the Linux kernel and associated packages using the +option `boot.kernelPackages`. For instance, this selects the Linux 3.10 +kernel: + +```nix +boot.kernelPackages = pkgs.linuxPackages_3_10; +``` + +Note that this not only replaces the kernel, but also packages that are +specific to the kernel version, such as the NVIDIA video drivers. This +ensures that driver packages are consistent with the kernel. + +The default Linux kernel configuration should be fine for most users. +You can see the configuration of your current kernel with the following +command: + +```ShellSession +zcat /proc/config.gz +``` + +If you want to change the kernel configuration, you can use the +`packageOverrides` feature (see [](#sec-customising-packages)). For +instance, to enable support for the kernel debugger KGDB: + +```nix +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; +``` + +`extraConfig` takes a list of Linux kernel configuration options, one +per line. The name of the option should not include the prefix +`CONFIG_`. The option value is typically `y`, `n` or `m` (to build +something as a kernel module). + +Kernel modules for hardware devices are generally loaded automatically +by `udev`. You can force a module to be loaded via +[`boot.kernelModules`](options.html#opt-boot.kernelModules), e.g. + +```nix +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +``` + +If the module is required early during the boot (e.g. to mount the root +file system), you can use [`boot.initrd.kernelModules`](options.html#opt-boot.initrd.kernelModules): + +```nix +boot.initrd.kernelModules = [ "cifs" ]; +``` + +This causes the specified modules and their dependencies to be added to +the initial ramdisk. + +Kernel runtime parameters can be set through +[`boot.kernel.sysctl`](options.html#opt-boot.kernel.sysctl), e.g. + +```nix +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; +``` + +sets the kernel's TCP keepalive time to 120 seconds. To see the +available parameters, run `sysctl -a`. + +## Customize your kernel {#sec-linux-config-customizing} + +The first step before compiling the kernel is to generate an appropriate +`.config` configuration. Either you pass your own config via the +`configfile` setting of `linuxManualConfig`: + +```nix +custom-kernel = super.linuxManualConfig { + inherit (super) stdenv hostPlatform; + inherit (linux_4_9) src; + version = "${linux_4_9.version}-custom"; + + configfile = /home/me/my_kernel_config; + allowImportFromDerivation = true; +}; +``` + +You can edit the config with this snippet (by default `make + menuconfig` won\'t work out of the box on nixos): + +```ShellSession +nix-shell -E 'with import {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' +``` + +or you can let nixpkgs generate the configuration. Nixpkgs generates it +via answering the interactive kernel utility `make config`. The answers +depend on parameters passed to +`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by +overriding `extraConfig, autoModules, + modDirVersion, preferBuiltin, extraConfig`). + +```nix +mptcp93.override ({ + name="mptcp-local"; + + ignoreConfigErrors = true; + autoModules = false; + kernelPreferBuiltin = true; + + enableParallelBuilding = true; + + extraConfig = '' + DEBUG_KERNEL y + FRAME_POINTER y + KGDB y + KGDB_SERIAL_CONSOLE y + DEBUG_INFO y + ''; +}); +``` + +## Developing kernel modules {#sec-linux-config-developing-modules} + +When developing kernel modules it\'s often convenient to run +edit-compile-run loop as quickly as possible. See below snippet as an +example of developing `mellanox` drivers. + +```ShellSession +$ nix-build '' -A linuxPackages.kernel.dev +$ nix-shell '' -A linuxPackages.kernel +$ unpackPhase +$ cd linux-* +$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules +# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko +``` diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml deleted file mode 100644 index 529ac1b1cd46..000000000000 --- a/nixos/doc/manual/configuration/linux-kernel.xml +++ /dev/null @@ -1,138 +0,0 @@ - - Linux Kernel - - You can override the Linux kernel and associated packages using the option - . For instance, this selects the Linux - 3.10 kernel: - - = pkgs.linuxPackages_3_10; - - Note that this not only replaces the kernel, but also packages that are - specific to the kernel version, such as the NVIDIA video drivers. This - ensures that driver packages are consistent with the kernel. - - - The default Linux kernel configuration should be fine for most users. You can - see the configuration of your current kernel with the following command: - -zcat /proc/config.gz - - If you want to change the kernel configuration, you can use the - feature (see - ). For instance, to enable support - for the kernel debugger KGDB: - -nixpkgs.config.packageOverrides = pkgs: - { linux_3_4 = pkgs.linux_3_4.override { - extraConfig = - '' - KGDB y - ''; - }; - }; - - extraConfig takes a list of Linux kernel configuration - options, one per line. The name of the option should not include the prefix - CONFIG_. The option value is typically - y, n or m (to build - something as a kernel module). - - - Kernel modules for hardware devices are generally loaded automatically by - udev. You can force a module to be loaded via - , e.g. - - = [ "fuse" "kvm-intel" "coretemp" ]; - - If the module is required early during the boot (e.g. to mount the root file - system), you can use : - - = [ "cifs" ]; - - This causes the specified modules and their dependencies to be added to the - initial ramdisk. - - - Kernel runtime parameters can be set through - , e.g. - -."net.ipv4.tcp_keepalive_time" = 120; - - sets the kernel’s TCP keepalive time to 120 seconds. To see the available - parameters, run sysctl -a. - -
- Customize your kernel - - - The first step before compiling the kernel is to generate an appropriate - .config configuration. Either you pass your own config - via the configfile setting of - linuxManualConfig: - - You can edit the config with this snippet (by default make - menuconfig won't work out of the box on nixos): - {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' - ]]> - or you can let nixpkgs generate the configuration. Nixpkgs generates it via - answering the interactive kernel utility make config. The - answers depend on parameters passed to - pkgs/os-specific/linux/kernel/generic.nix (which you - can influence by overriding extraConfig, autoModules, - modDirVersion, preferBuiltin, extraConfig). - - -
-
- Developing kernel modules - - - When developing kernel modules it's often convenient to run edit-compile-run - loop as quickly as possible. See below snippet as an example of developing - mellanox drivers. - - - -$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev -$ nix-shell '<nixpkgs>' -A linuxPackages.kernel -$ unpackPhase -$ cd linux-* -$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules -# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko - -
- diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml new file mode 100644 index 000000000000..b9be041e59b0 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml @@ -0,0 +1,153 @@ + + Linux Kernel + + You can override the Linux kernel and associated packages using the + option boot.kernelPackages. For instance, this + selects the Linux 3.10 kernel: + + +boot.kernelPackages = pkgs.linuxPackages_3_10; + + + Note that this not only replaces the kernel, but also packages that + are specific to the kernel version, such as the NVIDIA video + drivers. This ensures that driver packages are consistent with the + kernel. + + + The default Linux kernel configuration should be fine for most + users. You can see the configuration of your current kernel with the + following command: + + +zcat /proc/config.gz + + + If you want to change the kernel configuration, you can use the + packageOverrides feature (see + ). For instance, to + enable support for the kernel debugger KGDB: + + +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; + + + extraConfig takes a list of Linux kernel + configuration options, one per line. The name of the option should + not include the prefix CONFIG_. The option value + is typically y, n or + m (to build something as a kernel module). + + + Kernel modules for hardware devices are generally loaded + automatically by udev. You can force a module to + be loaded via + boot.kernelModules, + e.g. + + +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; + + + If the module is required early during the boot (e.g. to mount the + root file system), you can use + boot.initrd.kernelModules: + + +boot.initrd.kernelModules = [ "cifs" ]; + + + This causes the specified modules and their dependencies to be added + to the initial ramdisk. + + + Kernel runtime parameters can be set through + boot.kernel.sysctl, + e.g. + + +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; + + + sets the kernel’s TCP keepalive time to 120 seconds. To see the + available parameters, run sysctl -a. + +
+ Customize your kernel + + The first step before compiling the kernel is to generate an + appropriate .config configuration. Either you + pass your own config via the configfile setting + of linuxManualConfig: + + +custom-kernel = super.linuxManualConfig { + inherit (super) stdenv hostPlatform; + inherit (linux_4_9) src; + version = "${linux_4_9.version}-custom"; + + configfile = /home/me/my_kernel_config; + allowImportFromDerivation = true; +}; + + + You can edit the config with this snippet (by default + make menuconfig won't work out of the box on + nixos): + + +nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' + + + or you can let nixpkgs generate the configuration. Nixpkgs + generates it via answering the interactive kernel utility + make config. The answers depend on parameters + passed to + pkgs/os-specific/linux/kernel/generic.nix + (which you can influence by overriding + extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig). + + +mptcp93.override ({ + name="mptcp-local"; + + ignoreConfigErrors = true; + autoModules = false; + kernelPreferBuiltin = true; + + enableParallelBuilding = true; + + extraConfig = '' + DEBUG_KERNEL y + FRAME_POINTER y + KGDB y + KGDB_SERIAL_CONSOLE y + DEBUG_INFO y + ''; +}); + +
+
+ Developing kernel modules + + When developing kernel modules it's often convenient to run + edit-compile-run loop as quickly as possible. See below snippet as + an example of developing mellanox drivers. + + +$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev +$ nix-shell '<nixpkgs>' -A linuxPackages.kernel +$ unpackPhase +$ cd linux-* +$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules +# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko + +
+ From ee807a30cf093a0d16944350122cf5223c56629f Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:40:53 +0800 Subject: [PATCH 07/10] nixos: nixos/doc/manual/configuration/subversion.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../configuration/subversion.chapter.md | 102 +++++++++++++ nixos/doc/manual/configuration/subversion.xml | 140 ------------------ .../configuration/subversion.chapter.xml | 122 +++++++++++++++ 4 files changed, 225 insertions(+), 141 deletions(-) create mode 100644 nixos/doc/manual/configuration/subversion.chapter.md delete mode 100644 nixos/doc/manual/configuration/subversion.xml create mode 100644 nixos/doc/manual/from_md/configuration/subversion.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 56574680f9c3..a1d0d139aa5f 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -23,7 +23,7 @@ - + diff --git a/nixos/doc/manual/configuration/subversion.chapter.md b/nixos/doc/manual/configuration/subversion.chapter.md new file mode 100644 index 000000000000..72efdb09acbb --- /dev/null +++ b/nixos/doc/manual/configuration/subversion.chapter.md @@ -0,0 +1,102 @@ +# Subversion {#module-services-subversion} + +[Subversion](https://subversion.apache.org/) is a centralized +version-control system. It can use a [variety of +protocols](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing) +for communication between client and server. + +## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd} + +This section focuses on configuring a web-based server on top of the +Apache HTTP server, which uses +[WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm) +for communication. + +For more information on the general setup, please refer to the [the +appropriate section of the Subversion +book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd). + +To configure, include in `/etc/nixos/configuration.nix` code to activate +Apache HTTP, setting [`services.httpd.adminAddr`](options.html#opt-services.httpd.adminAddr) +appropriately: + +```nix +services.httpd.enable = true; +services.httpd.adminAddr = ...; +networking.firewall.allowedTCPPorts = [ 80 443 ]; +``` + +For a simple Subversion server with basic authentication, configure the +Subversion module for Apache as follows, setting `hostName` and +`documentRoot` appropriately, and `SVNParentPath` to the parent +directory of the repositories, `AuthzSVNAccessFile` to the location of +the `.authz` file describing access permission, and `AuthUserFile` to +the password file. + +```nix +services.httpd.extraModules = [ + # note that order is *super* important here + { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; } + { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; } + ]; + services.httpd.virtualHosts = { + "svn" = { + hostName = HOSTNAME; + documentRoot = DOCUMENTROOT; + locations."/svn".extraConfig = '' + DAV svn + SVNParentPath REPO_PARENT + AuthzSVNAccessFile ACCESS_FILE + AuthName "SVN Repositories" + AuthType Basic + AuthUserFile PASSWORD_FILE + Require valid-user + ''; + } +``` + +The key `"svn"` is just a symbolic name identifying the virtual host. +The `"/svn"` in `locations."/svn".extraConfig` is the path underneath +which the repositories will be served. + +[This page](https://wiki.archlinux.org/index.php/Subversion) explains +how to set up the Subversion configuration itself. This boils down to +the following: + +Underneath `REPO_PARENT` repositories can be set up as follows: + +```ShellSession +$ svn create REPO_NAME +``` + +Repository files need to be accessible by `wwwrun`: + +```ShellSession +$ chown -R wwwrun:wwwrun REPO_PARENT +``` + +The password file `PASSWORD_FILE` can be created as follows: + +```ShellSession +$ htpasswd -cs PASSWORD_FILE USER_NAME +``` + +Additional users can be set up similarly, omitting the `c` flag: + +```ShellSession +$ htpasswd -s PASSWORD_FILE USER_NAME +``` + +The file describing access permissions `ACCESS_FILE` will look something +like the following: + +```nix +[/] +* = r + +[REPO_NAME:/] +USER_NAME = rw +``` + +The Subversion repositories will be accessible as +`http://HOSTNAME/svn/REPO_NAME`. diff --git a/nixos/doc/manual/configuration/subversion.xml b/nixos/doc/manual/configuration/subversion.xml deleted file mode 100644 index 940d63cc4e6d..000000000000 --- a/nixos/doc/manual/configuration/subversion.xml +++ /dev/null @@ -1,140 +0,0 @@ - - Subversion - - - Subversion - is a centralized version-control system. It can use a variety - of protocols for communication between client and server. - -
- Subversion inside Apache HTTP - - - This section focuses on configuring a web-based server on top of - the Apache HTTP server, which uses - WebDAV/DeltaV - for communication. - - - For more information on the general setup, please refer to - the the - appropriate section of the Subversion book. - - - To configure, include in - /etc/nixos/configuration.nix code to activate - Apache HTTP, setting - appropriately: - - - - - services.httpd.enable = true; - services.httpd.adminAddr = ...; - networking.firewall.allowedTCPPorts = [ 80 443 ]; - - - - For a simple Subversion server with basic authentication, - configure the Subversion module for Apache as follows, setting - hostName and documentRoot - appropriately, and SVNParentPath to the parent - directory of the repositories, - AuthzSVNAccessFile to the location of the - .authz file describing access permission, and - AuthUserFile to the password file. - - - -services.httpd.extraModules = [ - # note that order is *super* important here - { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; } - { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; } - ]; - services.httpd.virtualHosts = { - "svn" = { - hostName = HOSTNAME; - documentRoot = DOCUMENTROOT; - locations."/svn".extraConfig = '' - DAV svn - SVNParentPath REPO_PARENT - AuthzSVNAccessFile ACCESS_FILE - AuthName "SVN Repositories" - AuthType Basic - AuthUserFile PASSWORD_FILE - Require valid-user - ''; - } - - - - - The key "svn" is just a symbolic name identifying the - virtual host. The "/svn" in - locations."/svn".extraConfig is the path underneath - which the repositories will be served. - - - This - page explains how to set up the Subversion configuration - itself. This boils down to the following: - - - Underneath REPO_PARENT repositories can be set up - as follows: - - - -$ svn create REPO_NAME - - - Repository files need to be accessible by - wwwrun: - - - -$ chown -R wwwrun:wwwrun REPO_PARENT - - - - The password file PASSWORD_FILE can be created as follows: - - - -$ htpasswd -cs PASSWORD_FILE USER_NAME - - - - Additional users can be set up similarly, omitting the - c flag: - - - -$ htpasswd -s PASSWORD_FILE USER_NAME - - - - The file describing access permissions - ACCESS_FILE will look something like - the following: - - - -[/] -* = r - -[REPO_NAME:/] -USER_NAME = rw - - - The Subversion repositories will be accessible as http://HOSTNAME/svn/REPO_NAME. -
- diff --git a/nixos/doc/manual/from_md/configuration/subversion.chapter.xml b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml new file mode 100644 index 000000000000..3bea116d498c --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml @@ -0,0 +1,122 @@ + + Subversion + + Subversion + is a centralized version-control system. It can use a + variety + of protocols for communication between client and server. + +
+ Subversion inside Apache HTTP + + This section focuses on configuring a web-based server on top of + the Apache HTTP server, which uses + WebDAV/DeltaV + for communication. + + + For more information on the general setup, please refer to the + the + appropriate section of the Subversion book. + + + To configure, include in + /etc/nixos/configuration.nix code to activate + Apache HTTP, setting + services.httpd.adminAddr + appropriately: + + +services.httpd.enable = true; +services.httpd.adminAddr = ...; +networking.firewall.allowedTCPPorts = [ 80 443 ]; + + + For a simple Subversion server with basic authentication, + configure the Subversion module for Apache as follows, setting + hostName and documentRoot + appropriately, and SVNParentPath to the parent + directory of the repositories, + AuthzSVNAccessFile to the location of the + .authz file describing access permission, and + AuthUserFile to the password file. + + +services.httpd.extraModules = [ + # note that order is *super* important here + { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; } + { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; } + ]; + services.httpd.virtualHosts = { + "svn" = { + hostName = HOSTNAME; + documentRoot = DOCUMENTROOT; + locations."/svn".extraConfig = '' + DAV svn + SVNParentPath REPO_PARENT + AuthzSVNAccessFile ACCESS_FILE + AuthName "SVN Repositories" + AuthType Basic + AuthUserFile PASSWORD_FILE + Require valid-user + ''; + } + + + The key "svn" is just a symbolic name + identifying the virtual host. The + "/svn" in + locations."/svn".extraConfig is the + path underneath which the repositories will be served. + + + This + page explains how to set up the Subversion configuration + itself. This boils down to the following: + + + Underneath REPO_PARENT repositories can be set + up as follows: + + +$ svn create REPO_NAME + + + Repository files need to be accessible by + wwwrun: + + +$ chown -R wwwrun:wwwrun REPO_PARENT + + + The password file PASSWORD_FILE can be created + as follows: + + +$ htpasswd -cs PASSWORD_FILE USER_NAME + + + Additional users can be set up similarly, omitting the + c flag: + + +$ htpasswd -s PASSWORD_FILE USER_NAME + + + The file describing access permissions + ACCESS_FILE will look something like the + following: + + +[/] +* = r + +[REPO_NAME:/] +USER_NAME = rw + + + The Subversion repositories will be accessible as + http://HOSTNAME/svn/REPO_NAME. + +
+ From f8bdee0054668f1ac7b30679e5ce6f5b95f160ee Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:41:27 +0800 Subject: [PATCH 08/10] nixos: nixos/doc/manual/configuration/kubernetes.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../configuration/kubernetes.chapter.md | 104 ++++++++++++++ nixos/doc/manual/configuration/kubernetes.xml | 112 --------------- .../configuration/kubernetes.chapter.xml | 130 ++++++++++++++++++ 4 files changed, 235 insertions(+), 113 deletions(-) create mode 100644 nixos/doc/manual/configuration/kubernetes.chapter.md delete mode 100644 nixos/doc/manual/configuration/kubernetes.xml create mode 100644 nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index a1d0d139aa5f..2461a5de73ad 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -26,6 +26,6 @@ - + diff --git a/nixos/doc/manual/configuration/kubernetes.chapter.md b/nixos/doc/manual/configuration/kubernetes.chapter.md new file mode 100644 index 000000000000..09a076a610b1 --- /dev/null +++ b/nixos/doc/manual/configuration/kubernetes.chapter.md @@ -0,0 +1,104 @@ +# Kubernetes {#sec-kubernetes} + +The NixOS Kubernetes module is a collective term for a handful of +individual submodules implementing the Kubernetes cluster components. + +There are generally two ways of enabling Kubernetes on NixOS. One way is +to enable and configure cluster components appropriately by hand: + +```nix +services.kubernetes = { + apiserver.enable = true; + controllerManager.enable = true; + scheduler.enable = true; + addonManager.enable = true; + proxy.enable = true; + flannel.enable = true; +}; +``` + +Another way is to assign cluster roles (\"master\" and/or \"node\") to +the host. This enables apiserver, controllerManager, scheduler, +addonManager, kube-proxy and etcd: + +```nix +services.kubernetes.roles = [ "master" ]; +``` + +While this will enable the kubelet and kube-proxy only: + +```nix +services.kubernetes.roles = [ "node" ]; +``` + +Assigning both the master and node roles is usable if you want a single +node Kubernetes cluster for dev or testing purposes: + +```nix +services.kubernetes.roles = [ "master" "node" ]; +``` + +Note: Assigning either role will also default both +[`services.kubernetes.flannel.enable`](options.html#opt-services.kubernetes.flannel.enable) +and [`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts) +to true. This sets up flannel as CNI and activates automatic PKI bootstrapping. + +As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled +ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP +ports have been disabled by default. While opening insecure ports is +still possible, it is recommended not to bind these to other interfaces +than loopback. To re-enable the insecure port on the apiserver, see options: +[`services.kubernetes.apiserver.insecurePort`](options.html#opt-services.kubernetes.apiserver.insecurePort) and +[`services.kubernetes.apiserver.insecureBindAddress`](options.html#opt-services.kubernetes.apiserver.insecureBindAddress) + +::: {.note} +As of NixOS 19.03, it is mandatory to configure: +[`services.kubernetes.masterAddress`](options.html#opt-services.kubernetes.masterAddress). +The masterAddress must be resolveable and routeable by all cluster nodes. +In single node clusters, this can be set to `localhost`. +::: + +Role-based access control (RBAC) authorization mode is enabled by +default. This means that anonymous requests to the apiserver secure port +will expectedly cause a permission denied error. All cluster components +must therefore be configured with x509 certificates for two-way tls +communication. The x509 certificate subject section determines the roles +and permissions granted by the apiserver to perform clusterwide or +namespaced operations. See also: [ Using RBAC +Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). + +The NixOS kubernetes module provides an option for automatic certificate +bootstrapping and configuration, +[`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts). +The PKI bootstrapping process involves setting up a certificate authority (CA) +daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert +for the cluster, and uses the CA-cert for signing subordinate certs issued +to each of the cluster components. Subsequently, the certmgr daemon monitors +active certificates and renews them when needed. For single node Kubernetes +clusters, setting [`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts) += true is sufficient and no further action is required. For joining extra node +machines to an existing cluster on the other hand, establishing initial +trust is mandatory. + +To add new nodes to the cluster: On any (non-master) cluster node where +[`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts) +is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH. +Given a token on stdin, it will copy the token to the kubernetes secrets directory +and restart the certmgr service. As requested certificates are issued, the +script will restart kubernetes cluster components as needed for them to +pick up new keypairs. + +::: {.note} +Multi-master (HA) clusters are not supported by the easyCerts module. +::: + +In order to interact with an RBAC-enabled cluster as an administrator, +one needs to have cluster-admin privileges. By default, when easyCerts +is enabled, a cluster-admin kubeconfig file is generated and linked into +`/etc/kubernetes/cluster-admin.kubeconfig` as determined by +[`services.kubernetes.pki.etcClusterAdminKubeconfig`](options.html#opt-services.kubernetes.pki.etcClusterAdminKubeconfig). +`export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make +kubectl use this kubeconfig to access and authenticate the cluster. The +cluster-admin kubeconfig references an auto-generated keypair owned by +root. Thus, only root on the kubernetes master may obtain cluster-admin +rights by means of this file. diff --git a/nixos/doc/manual/configuration/kubernetes.xml b/nixos/doc/manual/configuration/kubernetes.xml deleted file mode 100644 index 54a100e44795..000000000000 --- a/nixos/doc/manual/configuration/kubernetes.xml +++ /dev/null @@ -1,112 +0,0 @@ - - Kubernetes - - The NixOS Kubernetes module is a collective term for a handful of individual - submodules implementing the Kubernetes cluster components. - - - There are generally two ways of enabling Kubernetes on NixOS. One way is to - enable and configure cluster components appropriately by hand: - -services.kubernetes = { - apiserver.enable = true; - controllerManager.enable = true; - scheduler.enable = true; - addonManager.enable = true; - proxy.enable = true; - flannel.enable = true; -}; - - Another way is to assign cluster roles ("master" and/or "node") to the host. - This enables apiserver, controllerManager, scheduler, addonManager, - kube-proxy and etcd: - - = [ "master" ]; - - While this will enable the kubelet and kube-proxy only: - - = [ "node" ]; - - Assigning both the master and node roles is usable if you want a single node - Kubernetes cluster for dev or testing purposes: - - = [ "master" "node" ]; - - Note: Assigning either role will also default both - and - to true. This sets up - flannel as CNI and activates automatic PKI bootstrapping. - - - As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports - on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have - been disabled by default. While opening insecure ports is still possible, it - is recommended not to bind these to other interfaces than loopback. To - re-enable the insecure port on the apiserver, see options: - and - - - - - As of NixOS 19.03, it is mandatory to configure: - . The masterAddress - must be resolveable and routeable by all cluster nodes. In single node - clusters, this can be set to localhost. - - - - Role-based access control (RBAC) authorization mode is enabled by default. - This means that anonymous requests to the apiserver secure port will - expectedly cause a permission denied error. All cluster components must - therefore be configured with x509 certificates for two-way tls communication. - The x509 certificate subject section determines the roles and permissions - granted by the apiserver to perform clusterwide or namespaced operations. See - also: - - Using RBAC Authorization. - - - The NixOS kubernetes module provides an option for automatic certificate - bootstrapping and configuration, - . The PKI bootstrapping - process involves setting up a certificate authority (CA) daemon (cfssl) on - the kubernetes master node. cfssl generates a CA-cert for the cluster, and - uses the CA-cert for signing subordinate certs issued to each of the cluster - components. Subsequently, the certmgr daemon monitors active certificates and - renews them when needed. For single node Kubernetes clusters, setting - = true is sufficient and - no further action is required. For joining extra node machines to an existing - cluster on the other hand, establishing initial trust is mandatory. - - - To add new nodes to the cluster: On any (non-master) cluster node where - is enabled, the helper - script nixos-kubernetes-node-join is available on PATH. - Given a token on stdin, it will copy the token to the kubernetes secrets - directory and restart the certmgr service. As requested certificates are - issued, the script will restart kubernetes cluster components as needed for - them to pick up new keypairs. - - - - Multi-master (HA) clusters are not supported by the easyCerts module. - - - - In order to interact with an RBAC-enabled cluster as an administrator, one - needs to have cluster-admin privileges. By default, when easyCerts is - enabled, a cluster-admin kubeconfig file is generated and linked into - /etc/kubernetes/cluster-admin.kubeconfig as determined by - . - export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig - will make kubectl use this kubeconfig to access and authenticate the cluster. - The cluster-admin kubeconfig references an auto-generated keypair owned by - root. Thus, only root on the kubernetes master may obtain cluster-admin - rights by means of this file. - - diff --git a/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml new file mode 100644 index 000000000000..2707101ccf8c --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml @@ -0,0 +1,130 @@ + + Kubernetes + + The NixOS Kubernetes module is a collective term for a handful of + individual submodules implementing the Kubernetes cluster + components. + + + There are generally two ways of enabling Kubernetes on NixOS. One + way is to enable and configure cluster components appropriately by + hand: + + +services.kubernetes = { + apiserver.enable = true; + controllerManager.enable = true; + scheduler.enable = true; + addonManager.enable = true; + proxy.enable = true; + flannel.enable = true; +}; + + + Another way is to assign cluster roles ("master" and/or + "node") to the host. This enables apiserver, + controllerManager, scheduler, addonManager, kube-proxy and etcd: + + +services.kubernetes.roles = [ "master" ]; + + + While this will enable the kubelet and kube-proxy only: + + +services.kubernetes.roles = [ "node" ]; + + + Assigning both the master and node roles is usable if you want a + single node Kubernetes cluster for dev or testing purposes: + + +services.kubernetes.roles = [ "master" "node" ]; + + + Note: Assigning either role will also default both + services.kubernetes.flannel.enable + and + services.kubernetes.easyCerts + to true. This sets up flannel as CNI and activates automatic PKI + bootstrapping. + + + As of kubernetes 1.10.X it has been deprecated to open + non-tls-enabled ports on kubernetes components. Thus, from NixOS + 19.03 all plain HTTP ports have been disabled by default. While + opening insecure ports is still possible, it is recommended not to + bind these to other interfaces than loopback. To re-enable the + insecure port on the apiserver, see options: + services.kubernetes.apiserver.insecurePort + and + services.kubernetes.apiserver.insecureBindAddress + + + + As of NixOS 19.03, it is mandatory to configure: + services.kubernetes.masterAddress. + The masterAddress must be resolveable and routeable by all cluster + nodes. In single node clusters, this can be set to + localhost. + + + + Role-based access control (RBAC) authorization mode is enabled by + default. This means that anonymous requests to the apiserver secure + port will expectedly cause a permission denied error. All cluster + components must therefore be configured with x509 certificates for + two-way tls communication. The x509 certificate subject section + determines the roles and permissions granted by the apiserver to + perform clusterwide or namespaced operations. See also: + + Using RBAC Authorization. + + + The NixOS kubernetes module provides an option for automatic + certificate bootstrapping and configuration, + services.kubernetes.easyCerts. + The PKI bootstrapping process involves setting up a certificate + authority (CA) daemon (cfssl) on the kubernetes master node. cfssl + generates a CA-cert for the cluster, and uses the CA-cert for + signing subordinate certs issued to each of the cluster components. + Subsequently, the certmgr daemon monitors active certificates and + renews them when needed. For single node Kubernetes clusters, + setting + services.kubernetes.easyCerts + = true is sufficient and no further action is required. For joining + extra node machines to an existing cluster on the other hand, + establishing initial trust is mandatory. + + + To add new nodes to the cluster: On any (non-master) cluster node + where + services.kubernetes.easyCerts + is enabled, the helper script + nixos-kubernetes-node-join is available on PATH. + Given a token on stdin, it will copy the token to the kubernetes + secrets directory and restart the certmgr service. As requested + certificates are issued, the script will restart kubernetes cluster + components as needed for them to pick up new keypairs. + + + + Multi-master (HA) clusters are not supported by the easyCerts + module. + + + + In order to interact with an RBAC-enabled cluster as an + administrator, one needs to have cluster-admin privileges. By + default, when easyCerts is enabled, a cluster-admin kubeconfig file + is generated and linked into + /etc/kubernetes/cluster-admin.kubeconfig as + determined by + services.kubernetes.pki.etcClusterAdminKubeconfig. + export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig + will make kubectl use this kubeconfig to access and authenticate the + cluster. The cluster-admin kubeconfig references an auto-generated + keypair owned by root. Thus, only root on the kubernetes master may + obtain cluster-admin rights by means of this file. + + From ad393d5f63ebbf52b9c3977041910632ea30699c Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sun, 4 Jul 2021 08:24:44 +0800 Subject: [PATCH 09/10] nixos: use only URI fragment in manual options links --- .../manual/configuration/gpu-accel.chapter.md | 12 +++--- .../configuration/kubernetes.chapter.md | 18 ++++---- .../configuration/linux-kernel.chapter.md | 6 +-- .../sshfs-file-systems.section.md | 2 +- .../configuration/subversion.chapter.md | 2 +- .../manual/configuration/user-mgmt.chapter.md | 4 +- .../manual/configuration/wayland.chapter.md | 2 +- .../manual/configuration/x-windows.chapter.md | 4 +- .../doc/manual/configuration/xfce.chapter.md | 6 +-- .../configuration/gpu-accel.chapter.xml | 31 ++++++-------- .../configuration/kubernetes.chapter.xml | 42 +++++++++---------- .../configuration/linux-kernel.chapter.xml | 9 ++-- .../sshfs-file-systems.section.xml | 4 +- .../configuration/subversion.chapter.xml | 3 +- .../configuration/user-mgmt.chapter.xml | 14 +++---- .../from_md/configuration/wayland.chapter.xml | 3 +- .../configuration/x-windows.chapter.xml | 10 ++--- .../from_md/configuration/xfce.chapter.xml | 8 ++-- 18 files changed, 81 insertions(+), 99 deletions(-) diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md index 5540250e1da7..fd7b772c452b 100644 --- a/nixos/doc/manual/configuration/gpu-accel.chapter.md +++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md @@ -30,7 +30,7 @@ $ export \ ``` The second mechanism is to add the OpenCL driver package to -[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages). +[](#opt-hardware.opengl.extraPackages). This links the ICD file under `/run/opengl-driver`, where it will be visible to the ICD loader. @@ -51,7 +51,7 @@ Platform Vendor Advanced Micro Devices, Inc. Modern AMD [Graphics Core Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are supported through the rocm-opencl-icd package. Adding this package to -[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +[](#opt-hardware.opengl.extraPackages) enables OpenCL support: ```nix @@ -71,7 +71,7 @@ proprietary Intel OpenCL runtime, in the intel-ocl package, is an alternative for Gen7 GPUs. The intel-compute-runtime, beignet, or intel-ocl package can be added to -[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +[](#opt-hardware.opengl.extraPackages) to enable OpenCL support. For example, for Gen8 and later GPUs, the following configuration can be used: @@ -88,7 +88,7 @@ compute API for GPUs. It is used directly by games or indirectly though compatibility layers like [DXVK](https://github.com/doitsujin/dxvk/wiki). -By default, if [`hardware.opengl.driSupport`](options.html#opt-hardware.opengl.driSupport) +By default, if [](#opt-hardware.opengl.driSupport) is enabled, mesa is installed and provides Vulkan for supported hardware. Similar to OpenCL, Vulkan drivers are loaded through the *Installable @@ -108,7 +108,7 @@ $ export \ ``` The second mechanism is to add the Vulkan driver package to -[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages). +[](#opt-hardware.opengl.extraPackages). This links the ICD file under `/run/opengl-driver`, where it will be visible to the ICD loader. @@ -138,7 +138,7 @@ Modern AMD [Graphics Core Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are supported through either radv, which is part of mesa, or the amdvlk package. Adding the amdvlk package to -[`hardware.opengl.extraPackages`](options.html#opt-hardware.opengl.extraPackages) +[](#opt-hardware.opengl.extraPackages) makes amdvlk the default driver and hides radv and lavapipe from the device list. A specific driver can be forced as follows: diff --git a/nixos/doc/manual/configuration/kubernetes.chapter.md b/nixos/doc/manual/configuration/kubernetes.chapter.md index 09a076a610b1..93787577be9b 100644 --- a/nixos/doc/manual/configuration/kubernetes.chapter.md +++ b/nixos/doc/manual/configuration/kubernetes.chapter.md @@ -39,8 +39,8 @@ services.kubernetes.roles = [ "master" "node" ]; ``` Note: Assigning either role will also default both -[`services.kubernetes.flannel.enable`](options.html#opt-services.kubernetes.flannel.enable) -and [`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts) +[](#opt-services.kubernetes.flannel.enable) +and [](#opt-services.kubernetes.easyCerts) to true. This sets up flannel as CNI and activates automatic PKI bootstrapping. As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled @@ -48,12 +48,12 @@ ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have been disabled by default. While opening insecure ports is still possible, it is recommended not to bind these to other interfaces than loopback. To re-enable the insecure port on the apiserver, see options: -[`services.kubernetes.apiserver.insecurePort`](options.html#opt-services.kubernetes.apiserver.insecurePort) and -[`services.kubernetes.apiserver.insecureBindAddress`](options.html#opt-services.kubernetes.apiserver.insecureBindAddress) +[](#opt-services.kubernetes.apiserver.insecurePort) and +[](#opt-services.kubernetes.apiserver.insecureBindAddress) ::: {.note} As of NixOS 19.03, it is mandatory to configure: -[`services.kubernetes.masterAddress`](options.html#opt-services.kubernetes.masterAddress). +[](#opt-services.kubernetes.masterAddress). The masterAddress must be resolveable and routeable by all cluster nodes. In single node clusters, this can be set to `localhost`. ::: @@ -69,19 +69,19 @@ Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). The NixOS kubernetes module provides an option for automatic certificate bootstrapping and configuration, -[`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts). +[](#opt-services.kubernetes.easyCerts). The PKI bootstrapping process involves setting up a certificate authority (CA) daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert for the cluster, and uses the CA-cert for signing subordinate certs issued to each of the cluster components. Subsequently, the certmgr daemon monitors active certificates and renews them when needed. For single node Kubernetes -clusters, setting [`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts) +clusters, setting [](#opt-services.kubernetes.easyCerts) = true is sufficient and no further action is required. For joining extra node machines to an existing cluster on the other hand, establishing initial trust is mandatory. To add new nodes to the cluster: On any (non-master) cluster node where -[`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts) +[](#opt-services.kubernetes.easyCerts) is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH. Given a token on stdin, it will copy the token to the kubernetes secrets directory and restart the certmgr service. As requested certificates are issued, the @@ -96,7 +96,7 @@ In order to interact with an RBAC-enabled cluster as an administrator, one needs to have cluster-admin privileges. By default, when easyCerts is enabled, a cluster-admin kubeconfig file is generated and linked into `/etc/kubernetes/cluster-admin.kubeconfig` as determined by -[`services.kubernetes.pki.etcClusterAdminKubeconfig`](options.html#opt-services.kubernetes.pki.etcClusterAdminKubeconfig). +[](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig). `export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make kubectl use this kubeconfig to access and authenticate the cluster. The cluster-admin kubeconfig references an auto-generated keypair owned by diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md index 95af16663891..aad6d49c72c3 100644 --- a/nixos/doc/manual/configuration/linux-kernel.chapter.md +++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md @@ -42,14 +42,14 @@ something as a kernel module). Kernel modules for hardware devices are generally loaded automatically by `udev`. You can force a module to be loaded via -[`boot.kernelModules`](options.html#opt-boot.kernelModules), e.g. +[](#opt-boot.kernelModules), e.g. ```nix boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; ``` If the module is required early during the boot (e.g. to mount the root -file system), you can use [`boot.initrd.kernelModules`](options.html#opt-boot.initrd.kernelModules): +file system), you can use [](#opt-boot.initrd.kernelModules): ```nix boot.initrd.kernelModules = [ "cifs" ]; @@ -59,7 +59,7 @@ This causes the specified modules and their dependencies to be added to the initial ramdisk. Kernel runtime parameters can be set through -[`boot.kernel.sysctl`](options.html#opt-boot.kernel.sysctl), e.g. +[](#opt-boot.kernel.sysctl), e.g. ```nix boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; diff --git a/nixos/doc/manual/configuration/sshfs-file-systems.section.md b/nixos/doc/manual/configuration/sshfs-file-systems.section.md index 4625fce03d58..4dd1b203a249 100644 --- a/nixos/doc/manual/configuration/sshfs-file-systems.section.md +++ b/nixos/doc/manual/configuration/sshfs-file-systems.section.md @@ -34,7 +34,7 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`: OpenSSH normally refuses to use the key if it's not well-protected. -The file system can be configured in NixOS via the usual [fileSystems](options.html#opt-fileSystems) option. +The file system can be configured in NixOS via the usual [fileSystems](#opt-fileSystems) option. Here's a typical setup: ```nix { diff --git a/nixos/doc/manual/configuration/subversion.chapter.md b/nixos/doc/manual/configuration/subversion.chapter.md index 72efdb09acbb..84f9c2703378 100644 --- a/nixos/doc/manual/configuration/subversion.chapter.md +++ b/nixos/doc/manual/configuration/subversion.chapter.md @@ -17,7 +17,7 @@ appropriate section of the Subversion book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd). To configure, include in `/etc/nixos/configuration.nix` code to activate -Apache HTTP, setting [`services.httpd.adminAddr`](options.html#opt-services.httpd.adminAddr) +Apache HTTP, setting [](#opt-services.httpd.adminAddr) appropriately: ```nix diff --git a/nixos/doc/manual/configuration/user-mgmt.chapter.md b/nixos/doc/manual/configuration/user-mgmt.chapter.md index 64eacc5f7dd6..37990664a8f1 100644 --- a/nixos/doc/manual/configuration/user-mgmt.chapter.md +++ b/nixos/doc/manual/configuration/user-mgmt.chapter.md @@ -24,10 +24,10 @@ log in via mechanisms that require a password. However, you can use the `passwd` program to set a password, which is retained across invocations of `nixos-rebuild`. -If you set [`users.mutableUsers`](options.html#opt-users.mutableUsers) to +If you set [](#opt-users.mutableUsers) to false, then the contents of `/etc/passwd` and `/etc/group` will be congruent to your NixOS configuration. For instance, if you remove a user from -[`users.users`](options.html#opt-users.users) and run nixos-rebuild, the user +[](#opt-users.users) and run nixos-rebuild, the user account will cease to exist. Also, imperative commands for managing users and groups, such as useradd, are no longer available. Passwords may still be assigned by setting the user\'s diff --git a/nixos/doc/manual/configuration/wayland.chapter.md b/nixos/doc/manual/configuration/wayland.chapter.md index 49c0cab38e5e..a3a46aa3da6f 100644 --- a/nixos/doc/manual/configuration/wayland.chapter.md +++ b/nixos/doc/manual/configuration/wayland.chapter.md @@ -23,5 +23,5 @@ xdg.portal.wlr.enable = true; ``` and configure Pipewire using -[`services.pipewire.enable`](options.html#opt-services.pipewire.enable) +[](#opt-services.pipewire.enable) and related options. diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md index d9a924d41d7d..2c80b786b267 100644 --- a/nixos/doc/manual/configuration/x-windows.chapter.md +++ b/nixos/doc/manual/configuration/x-windows.chapter.md @@ -115,7 +115,7 @@ officially updated since 2015. The results vary depending on the hardware, so you may have to try both drivers. Use the option -[`services.xserver.videoDrivers`](options.html#opt-services.xserver.videoDrivers) +[](#opt-services.xserver.videoDrivers) to set one. The recommended configuration for modern systems is: ```nix @@ -183,7 +183,7 @@ Latitude series) can be enabled as follows: services.xserver.libinput.enable = true; ``` -The driver has many options (see [Appendix A, Configuration Options](options.html)). +The driver has many options (see [](#ch-options)). For instance, the following disables tap-to-click behavior: ```nix diff --git a/nixos/doc/manual/configuration/xfce.chapter.md b/nixos/doc/manual/configuration/xfce.chapter.md index 3c0c5f3a6f38..b0ef6682aae8 100644 --- a/nixos/doc/manual/configuration/xfce.chapter.md +++ b/nixos/doc/manual/configuration/xfce.chapter.md @@ -22,13 +22,13 @@ services.picom = { Some Xfce programs are not installed automatically. To install them manually (system wide), put them into your -[`environment.systemPackages`](options.html#opt-environment.systemPackages) from `pkgs.xfce`. +[](#opt-environment.systemPackages) from `pkgs.xfce`. ## Thunar Plugins {#sec-xfce-thunar-plugins .unnumbered} If you\'d like to add extra plugins to Thunar, add them to -[`services.xserver.desktopManager.xfce.thunarPlugins`](options.html#opt-services.xserver.desktopManager.xfce.thunarPlugins). -You shouldn\'t just add them to [`environment.systemPackages`](options.html#opt-environment.systemPackages). +[](#opt-services.xserver.desktopManager.xfce.thunarPlugins). +You shouldn\'t just add them to [](#opt-environment.systemPackages). ## Troubleshooting {#sec-xfce-troubleshooting .unnumbered} diff --git a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml index ec6468101849..28fb86d57a50 100644 --- a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml @@ -36,10 +36,9 @@ $ export \ The second mechanism is to add the OpenCL driver package to - hardware.opengl.extraPackages. - This links the ICD file under - /run/opengl-driver, where it will be visible to - the ICD loader. + . This links + the ICD file under /run/opengl-driver, where it + will be visible to the ICD loader. The proper installation of OpenCL drivers can be verified through @@ -60,8 +59,8 @@ Platform Vendor Advanced Micro Devices, Inc. Graphics Core Next (GCN) GPUs are supported through the rocm-opencl-icd package. Adding this package to - hardware.opengl.extraPackages - enables OpenCL support: + enables + OpenCL support: hardware.opengl.extraPackages = [ @@ -82,10 +81,9 @@ hardware.opengl.extraPackages = [ The intel-compute-runtime, beignet, or intel-ocl package can be - added to - hardware.opengl.extraPackages - to enable OpenCL support. For example, for Gen8 and later GPUs, - the following configuration can be used: + added to to + enable OpenCL support. For example, for Gen8 and later GPUs, the + following configuration can be used: hardware.opengl.extraPackages = [ @@ -103,8 +101,7 @@ hardware.opengl.extraPackages = [ DXVK. - By default, if - hardware.opengl.driSupport + By default, if is enabled, mesa is installed and provides Vulkan for supported hardware. @@ -129,10 +126,9 @@ $ export \ The second mechanism is to add the Vulkan driver package to - hardware.opengl.extraPackages. - This links the ICD file under - /run/opengl-driver, where it will be visible to - the ICD loader. + . This links + the ICD file under /run/opengl-driver, where it + will be visible to the ICD loader. The proper installation of Vulkan drivers can be verified through @@ -162,8 +158,7 @@ GPU1: Graphics Core Next (GCN) GPUs are supported through either radv, which is part of mesa, or the amdvlk package. Adding the amdvlk - package to - hardware.opengl.extraPackages + package to makes amdvlk the default driver and hides radv and lavapipe from the device list. A specific driver can be forced as follows: diff --git a/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml index 2707101ccf8c..83a50d7c49d1 100644 --- a/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml @@ -43,11 +43,9 @@ services.kubernetes.roles = [ "master" "node" ]; Note: Assigning either role will also default both - services.kubernetes.flannel.enable - and - services.kubernetes.easyCerts - to true. This sets up flannel as CNI and activates automatic PKI - bootstrapping. + and + to true. This + sets up flannel as CNI and activates automatic PKI bootstrapping. As of kubernetes 1.10.X it has been deprecated to open @@ -56,15 +54,15 @@ services.kubernetes.roles = [ "master" "node" ]; opening insecure ports is still possible, it is recommended not to bind these to other interfaces than loopback. To re-enable the insecure port on the apiserver, see options: - services.kubernetes.apiserver.insecurePort + and - services.kubernetes.apiserver.insecureBindAddress + As of NixOS 19.03, it is mandatory to configure: - services.kubernetes.masterAddress. - The masterAddress must be resolveable and routeable by all cluster + . The + masterAddress must be resolveable and routeable by all cluster nodes. In single node clusters, this can be set to localhost. @@ -83,24 +81,22 @@ services.kubernetes.roles = [ "master" "node" ]; The NixOS kubernetes module provides an option for automatic certificate bootstrapping and configuration, - services.kubernetes.easyCerts. - The PKI bootstrapping process involves setting up a certificate - authority (CA) daemon (cfssl) on the kubernetes master node. cfssl - generates a CA-cert for the cluster, and uses the CA-cert for - signing subordinate certs issued to each of the cluster components. + . The PKI + bootstrapping process involves setting up a certificate authority + (CA) daemon (cfssl) on the kubernetes master node. cfssl generates a + CA-cert for the cluster, and uses the CA-cert for signing + subordinate certs issued to each of the cluster components. Subsequently, the certmgr daemon monitors active certificates and renews them when needed. For single node Kubernetes clusters, - setting - services.kubernetes.easyCerts - = true is sufficient and no further action is required. For joining - extra node machines to an existing cluster on the other hand, - establishing initial trust is mandatory. + setting = true + is sufficient and no further action is required. For joining extra + node machines to an existing cluster on the other hand, establishing + initial trust is mandatory. To add new nodes to the cluster: On any (non-master) cluster node - where - services.kubernetes.easyCerts - is enabled, the helper script + where is + enabled, the helper script nixos-kubernetes-node-join is available on PATH. Given a token on stdin, it will copy the token to the kubernetes secrets directory and restart the certmgr service. As requested @@ -120,7 +116,7 @@ services.kubernetes.roles = [ "master" "node" ]; is generated and linked into /etc/kubernetes/cluster-admin.kubeconfig as determined by - services.kubernetes.pki.etcClusterAdminKubeconfig. + . export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig will make kubectl use this kubeconfig to access and authenticate the cluster. The cluster-admin kubeconfig references an auto-generated diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml index b9be041e59b0..f804d0a3b8c2 100644 --- a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml @@ -48,9 +48,7 @@ nixpkgs.config.packageOverrides = pkgs: Kernel modules for hardware devices are generally loaded automatically by udev. You can force a module to - be loaded via - boot.kernelModules, - e.g. + be loaded via , e.g. boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; @@ -58,7 +56,7 @@ boot.kernelModules = [ "fuse" "kvm-intel" "coretemp&quo If the module is required early during the boot (e.g. to mount the root file system), you can use - boot.initrd.kernelModules: + : boot.initrd.kernelModules = [ "cifs" ]; @@ -69,8 +67,7 @@ boot.initrd.kernelModules = [ "cifs" ]; Kernel runtime parameters can be set through - boot.kernel.sysctl, - e.g. + , e.g. boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; diff --git a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml index 6b317aa63e9a..5d74712f35dc 100644 --- a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml +++ b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml @@ -51,8 +51,8 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation The file system can be configured in NixOS via the usual - fileSystems - option. Here’s a typical setup: + fileSystems option. Here’s + a typical setup: { diff --git a/nixos/doc/manual/from_md/configuration/subversion.chapter.xml b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml index 3bea116d498c..794c2c34e399 100644 --- a/nixos/doc/manual/from_md/configuration/subversion.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml @@ -23,8 +23,7 @@ To configure, include in /etc/nixos/configuration.nix code to activate Apache HTTP, setting - services.httpd.adminAddr - appropriately: + appropriately: services.httpd.enable = true; diff --git a/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml index b865fabfe3cc..06492d5c2512 100644 --- a/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml @@ -29,16 +29,14 @@ users.users.alice = { retained across invocations of nixos-rebuild. - If you set - users.mutableUsers - to false, then the contents of /etc/passwd and + If you set to false, then + the contents of /etc/passwd and /etc/group will be congruent to your NixOS configuration. For instance, if you remove a user from - users.users - and run nixos-rebuild, the user account will cease to exist. Also, - imperative commands for managing users and groups, such as useradd, - are no longer available. Passwords may still be assigned by setting - the user's + and run nixos-rebuild, the user + account will cease to exist. Also, imperative commands for managing + users and groups, such as useradd, are no longer available. + Passwords may still be assigned by setting the user's hashedPassword option. A hashed password can be generated using mkpasswd -m sha-512. diff --git a/nixos/doc/manual/from_md/configuration/wayland.chapter.xml b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml index 166925f67d22..1e90d4f31177 100644 --- a/nixos/doc/manual/from_md/configuration/wayland.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml @@ -26,7 +26,6 @@ xdg.portal.wlr.enable = true; and configure Pipewire using - services.pipewire.enable - and related options. + and related options. diff --git a/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml index 8e67c66f1526..274d0d817bc1 100644 --- a/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml @@ -128,8 +128,8 @@ services.xserver.displayManager.autoLogin.user = "alice"; The results vary depending on the hardware, so you may have to try both drivers. Use the option - services.xserver.videoDrivers - to set one. The recommended configuration for modern systems is: + to set one. + The recommended configuration for modern systems is: services.xserver.videoDrivers = [ "modesetting" ]; @@ -204,10 +204,8 @@ services.xserver.videoDrivers = [ "amdgpu-pro" ]; services.xserver.libinput.enable = true; - The driver has many options (see - Appendix A, Configuration - Options). For instance, the following disables tap-to-click - behavior: + The driver has many options (see ). + For instance, the following disables tap-to-click behavior: services.xserver.libinput.touchpad.tapping = false; diff --git a/nixos/doc/manual/from_md/configuration/xfce.chapter.xml b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml index 0066baa2dc70..f96ef2e8c483 100644 --- a/nixos/doc/manual/from_md/configuration/xfce.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml @@ -23,16 +23,16 @@ services.picom = { Some Xfce programs are not installed automatically. To install them manually (system wide), put them into your - environment.systemPackages - from pkgs.xfce. + from + pkgs.xfce.
Thunar Plugins If you'd like to add extra plugins to Thunar, add them to - services.xserver.desktopManager.xfce.thunarPlugins. + . You shouldn't just add them to - environment.systemPackages. + .
From 2d466c7adc2daa950290467f245b2d24a36231f6 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sun, 4 Jul 2021 08:29:41 +0800 Subject: [PATCH 10/10] nixos: improve indentation in nixos/doc/manual/configuration/gpu-accel.chapter.md --- .../manual/configuration/gpu-accel.chapter.md | 30 +++++++++---------- .../configuration/gpu-accel.chapter.xml | 30 +++++++++---------- 2 files changed, 30 insertions(+), 30 deletions(-) diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md index fd7b772c452b..08b6af5d98ae 100644 --- a/nixos/doc/manual/configuration/gpu-accel.chapter.md +++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md @@ -56,8 +56,8 @@ enables OpenCL support: ```nix hardware.opengl.extraPackages = [ - rocm-opencl-icd - ]; + rocm-opencl-icd +]; ``` ### Intel {#sec-gpu-accel-opencl-intel} @@ -77,8 +77,8 @@ configuration can be used: ```nix hardware.opengl.extraPackages = [ - intel-compute-runtime - ]; + intel-compute-runtime +]; ``` ## Vulkan {#sec-gpu-accel-vulkan} @@ -144,19 +144,19 @@ A specific driver can be forced as follows: ```nix hardware.opengl.extraPackages = [ - pkgs.amdvlk - ]; + pkgs.amdvlk +]; - # To enable Vulkan support for 32-bit applications, also add: - hardware.opengl.extraPackages32 = [ - pkgs.driversi686Linux.amdvlk - ]; +# To enable Vulkan support for 32-bit applications, also add: +hardware.opengl.extraPackages32 = [ + pkgs.driversi686Linux.amdvlk +]; - # Force radv - environment.variables.AMD_VULKAN_ICD = "RADV"; - # Or - environment.variables.VK_ICD_FILENAMES = - "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; +# Force radv +environment.variables.AMD_VULKAN_ICD = "RADV"; +# Or +environment.variables.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; ``` ## Common issues {#sec-gpu-accel-common-issues} diff --git a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml index 28fb86d57a50..8e780c5dee95 100644 --- a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml @@ -64,8 +64,8 @@ Platform Vendor Advanced Micro Devices, Inc. hardware.opengl.extraPackages = [ - rocm-opencl-icd - ]; + rocm-opencl-icd +];
@@ -87,8 +87,8 @@ hardware.opengl.extraPackages = [ hardware.opengl.extraPackages = [ - intel-compute-runtime - ]; + intel-compute-runtime +];
@@ -164,19 +164,19 @@ GPU1: hardware.opengl.extraPackages = [ - pkgs.amdvlk - ]; + pkgs.amdvlk +]; - # To enable Vulkan support for 32-bit applications, also add: - hardware.opengl.extraPackages32 = [ - pkgs.driversi686Linux.amdvlk - ]; +# To enable Vulkan support for 32-bit applications, also add: +hardware.opengl.extraPackages32 = [ + pkgs.driversi686Linux.amdvlk +]; - # Force radv - environment.variables.AMD_VULKAN_ICD = "RADV"; - # Or - environment.variables.VK_ICD_FILENAMES = - "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"; +# Force radv +environment.variables.AMD_VULKAN_ICD = "RADV"; +# Or +environment.variables.VK_ICD_FILENAMES = + "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";