Official NixOS Wiki

NFS: Difference between revisions

← Older edit
DHCP (talk | contribs)
232 edits
VisualWikitext
Pigs (talk | contribs)
275 edits
Adds btrfs section and refactored layout for readability. Decrease the example from 4 mounts to 2 mounts. The 4 examples made a lot of boilerplate and didn't show off any extra functionality that just 2 example nfs shares would show.
Tags: Mobile edit Mobile web edit Advanced mobile edit
DHCP (talk | contribs)
232 edits
m →Client: add missing $
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
__FORCETOC__
__FORCETOC__
[[wikipedia:Network_File_System|NFS]] is a distribute filesystem protocol to access directories and files over a network.
= Server =
= Server =


Line 5: Line 8:


=== Using bind mounts ===
=== Using bind mounts ===
When deploying NFS, it is considered best practice to bind mount directories to be shared to a "virtual root directory" (typically <code>/export</code>) as filesystems to be exported can be made available under a single directory.
{{Note|This section demonstrates a best-practice NFS deployment using a virtual root directory (as in [https://wiki.gentoo.org/wiki/NFSv4 nfs-utils - Gentoo wiki]). Instead the directory can be directly exported as follows:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
  services.nfs.server.enable = true;
  services.nfs.server.exports = ''
    /home    192.0.2.0/24(insecure,rw,sync,no_subtree_check)
  '';
}
</nowiki>}}
}}


Let's say that we've got one server-machine with 2 directories that we want to share: <code>/mnt/tomoyo</code> and <code>/mnt/kotomi</code>.
Let's say that we've got one server-machine with 2 directories that we want to share: <code>/mnt/tomoyo</code> and <code>/mnt/kotomi</code>.


First, we have to create a dedicated directory from which our NFS server will access the data:
First, we have to create a dedicated directory ("virtual root directory") from which our NFS server will access the data:


<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
Line 14: Line 31:
</syntaxhighlight>
</syntaxhighlight>


You may need to change ownership of the <code>/export</code> directory to <code>nobody:nogroup</code>
You may need to change ownership of the <code>/export</code> directory to <code>nobody:nogroup</code>.


Then we have to either move our already-existing directories inside <code>/export</code> (using <code>mv</code> from the command line) or bind-mount them there:
Next mount directories to the virtual root directory.


<syntaxhighlight lang="nix">
<syntaxhighlight lang="console">
# mount --bind /mnt/tomoyo /export/tomoyo
# mount --bind /mnt/kotomi /export/kotomi
</syntaxhighlight>
 
Generate hardware config:
 
<syntaxhighlight lang="console">
nixos-generate-config
</syntaxhighlight>
 
This will add the following to <code>hardware-configuration.nix</code>.
 
{{file|/etc/nixos/hardware-configuration.nix|nix|<nowiki>
{
{
   fileSystems."/export/tomoyo" = {
   fileSystems."/export/tomoyo" = {
     device = "/mnt/tomoyo";
     device = "/mnt/tomoyo";
    fsType = "none";
     options = [ "bind" ];
     options = [ "bind" ];
   };
   };
Line 27: Line 58:
   fileSystems."/export/kotomi" = {
   fileSystems."/export/kotomi" = {
     device = "/mnt/kotomi";
     device = "/mnt/kotomi";
    fsType = "none";
     options = [ "bind" ];
     options = [ "bind" ];
   };
   };
}
}
</syntaxhighlight>
</nowiki>}}
 
Refer to [[Filesystems#Bind mounts]] for more information on bind mounts.


=== Using btrfs subvolumes ===
=== Using btrfs subvolumes ===
Line 40: Line 74:
Having the filesystem ready, we can proceed to configure the NFS server itself:
Having the filesystem ready, we can proceed to configure the NFS server itself:


<syntaxhighlight lang="nix">
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
{
   services.nfs.server.enable = true;
   services.nfs.server.enable = true;
Line 49: Line 83:
   '';
   '';
}
}
</syntaxhighlight>
</nowiki>}}


This configuration exposes all our shares to 2 local IPs; you can find more examples at [https://wiki.gentoo.org/wiki/NFSv4 Gentoo's wiki on NFS].
This configuration exposes all our shares to 2 local IPs; you can find more examples at [https://wiki.gentoo.org/wiki/NFSv4 Gentoo's wiki on NFS].
To list the current loaded exports, use: <code>exportfs -v</code>


Other options are available on the [https://search.nixos.org/options?query=nfs NixOS option page] or via the <code>nixos-option</code> command.
Other options are available on the [https://search.nixos.org/options?query=nfs NixOS option page] or via the <code>nixos-option</code> command.
Line 84: Line 120:
= Client =
= Client =


To ensure the client has the necessary utilities installed, add
To ensure the client has the necessary NFS utilities installed to mount NFS drives, add "nfs" to {{nixos:option|boot.supportedFilesystems}}.
<syntaxhighlight lang="nix">
 
  boot.supportedFilesystems = [ "nfs" ];
{{file|/etc/nixos/hardware-configuration.nix|nix|<nowiki>
boot.supportedFilesystems = [ "nfs" ];
</nowiki>}}
 
{{warning|Without addding "nfs" to {{nixos:option|boot.supportedFilesystems}}, the following error will be raised when trying to mount them:
 
<syntaxhighlight lang="console">
# mount 192.0.2.1:/tomoyo /mnt/tomoyo
mount: /mnt/nfs: fsconfig system call failed: NFS: mount program didn't pass remote address.
      dmesg(1) may have more information after failed mount system call.
</syntaxhighlight>
}}
 
Next mount exports to your local directories:
 
<syntaxhighlight lang="console">
# mount 192.0.2.1:/tomoyo /mnt/tomoyo
# mount 192.0.2.1:/kotomi /mnt/kotomi
</syntaxhighlight>
</syntaxhighlight>


to your Nix configuration (e.g. <code>configuration.nix</code>) file.
{{Note|Replace "192.0.2.1" with the appropriate IP address or DNS entry of your NFS server.}}


Continuing the server example, mounting the now-exposed ''tomoyo'' share on another box (on a client) is as simple as:
{{note| On the client side, the exposed shares are as if they were exposed at the root level - i.e. <code>/export/foo</code> becomes <code>/foo</code> (in the <code>device</code> option) }}


<syntaxhighlight lang="nix">
Generate hardware config:
 
<syntaxhighlight lang="console">
$ nixos-generate-config
</syntaxhighlight>
 
This will add the following to <code>hardware-configuration.nix</code>.
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
{
   fileSystems."/mnt/tomoyo" = {
   fileSystems."/mnt/tomoyo" = {
     device = "server:/tomoyo";
     device = "192.0.2.1:/tomoyo";
     fsType = "nfs";
     fsType = "nfs4";
  };
 
  fileSystems."/mnt/kotomi" = {
    device = "192.0.2.1:/kotomi";
    fsType = "nfs4";
   };
   };
}
}
</syntaxhighlight>
</nowiki>}}
Replace "server" in the above device attribute with the IP address or DNS entry of the NFS server. Note that clients see exposed shares as if they were exposed at the root level - i.e. <code>/export/foo</code> becomes <code>/foo</code> (in the <code>device</code> option). Other, regular '''fileSystems''' options apply.
 
Other, regular [https://search.nixos.org/options?query=filesystems.%3Cname%3E filesystem options] apply.


== Specifying NFS version ==
== Specifying NFS version ==
Line 143: Line 210:
== Using systemd.mounts and systemd.automounts ==
== Using systemd.mounts and systemd.automounts ==


Here is an example with auto-disconnecting and lazy-mounting implemented, and the <code>noatime</code> mount option added.
This section provides an alternative approach for users who prefer to manage mounts using dedicated systemd units. Here is an example with auto-disconnecting and lazy-mounting implemented, and the <code>noatime</code> mount option added.


Note that <code>wantedBy = [ "multi-user.target" ];</code> is required for the automount unit to start at boot.  
Note that <code>wantedBy = [ "multi-user.target" ];</code> is required for the automount unit to start at boot.  
Line 219: Line 286:
<syntaxhighlight lang="console"><host_or_ip>/nix /nix nfs nofail,x-systemd.device-timeout=4,local_lock=all 0 0</syntaxhighlight>'''TODO:''' Why this? That seems extremely unsafe. This disables NFS locks (which apply to all NFS clients), and makes locks ''local'', meaning a lock taken by one NFS client isn't seen by another, and both can take their locks. So this removes protection against concurrent writes, which Nix assumes.
<syntaxhighlight lang="console"><host_or_ip>/nix /nix nfs nofail,x-systemd.device-timeout=4,local_lock=all 0 0</syntaxhighlight>'''TODO:''' Why this? That seems extremely unsafe. This disables NFS locks (which apply to all NFS clients), and makes locks ''local'', meaning a lock taken by one NFS client isn't seen by another, and both can take their locks. So this removes protection against concurrent writes, which Nix assumes.
[[Category:Filesystem]]
[[Category:Filesystem]]
[[Category:Networking]]
Retrieved from "https://wiki.nixos.org/wiki/NFS"