1.\" 2.\" CDDL HEADER START 3.\" 4.\" The contents of this file are subject to the terms of the 5.\" Common Development and Distribution License (the "License"). 6.\" You may not use this file except in compliance with the License. 7.\" 8.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9.\" or http://www.opensolaris.org/os/licensing. 10.\" See the License for the specific language governing permissions 11.\" and limitations under the License. 12.\" 13.\" When distributing Covered Code, include this CDDL HEADER in each 14.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15.\" If applicable, add the following below this CDDL HEADER, with the 16.\" fields enclosed by brackets "[]" replaced with your own identifying 17.\" information: Portions Copyright [yyyy] [name of copyright owner] 18.\" 19.\" CDDL HEADER END 20.\" 21.\" 22.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved 23.\" Copyright 2014 Nexenta Systems, Inc. All rights reserved. 24.\" Copyright 2016 Jason King. 25.\" 26.Dd November 22, 2021 27.Dt SHARE_NFS 8 28.Os 29.Sh NAME 30.Nm share_nfs 31.Nd make local NFS file systems available for mounting by remote systems 32.Sh SYNOPSIS 33.Nm share 34.Op Fl d Ar description 35.Op Fl F Sy nfs 36.Op Fl o Ar specific_options 37.Ar pathname 38.Sh DESCRIPTION 39The 40.Nm share 41utility makes local file systems available for mounting by remote systems. 42It starts the 43.Xr nfsd 8 44and 45.Xr mountd 8 46daemons if they are not already running. 47.Pp 48If no argument is specified, then 49.Nm share 50displays all file systems currently shared, including NFS file systems and file 51systems shared through other distributed file system packages. 52.Sh OPTIONS 53The following options are supported: 54.Bl -tag -width "indented" 55.It Fl d Ar description 56Provide a comment that describes the file system to be shared. 57.It Fl F Sy nfs 58Share NFS file system type. 59.It Fl o Ar specific_options 60Specify 61.Ar specific_options 62in a comma-separated list of keywords and attribute-value-assertions for 63interpretation by the file-system-type-specific command. 64If 65.Ar specific_options 66is not specified, then by default sharing is read-write to all clients. 67.Ar specific_options 68can be any combination of the following: 69.Bl -tag -width "indented" 70.It Sy aclok 71Allows the NFS server to do access control for NFS Version 2 clients (running 72SunOS 2.4 or earlier). 73When 74.Sy aclok 75is set on the server, maximal access is given to all clients. 76For example, with 77.Sy aclok 78set, if anyone has read permissions, then everyone does. 79If 80.Sy aclok 81is not set, minimal access is given to all clients. 82.It Sy anon Ns = Ns Ar uid 83Set 84.Ar uid 85to be the effective user ID of unknown users. 86By default, unknown users are given the effective user ID UID_NOBODY. 87If uid is set to -1, access is denied. 88.It Ar charset Ns = Ns Ar access_list 89Where 90.Ar charset 91is one of: euc-cn, euc-jp, euc-jpms, euc-kr, euc-tw, iso8859-1, iso8859-2, 92iso8859-5, iso8859-6, iso8859-7, iso8859-8, iso8859-9, iso8859-13, iso8859-15, 93koi8-r. 94.Pp 95Clients that match the 96.Ar access_list 97for one of these properties will be assumed to be using that character set and 98file and path names will be converted to UTF-8 for the server. 99.It Sy gidmap Ns = Ns Ar mapping Ns Oo ~ Ns Ar mapping Oc Ns ... 100Where 101.Ar mapping 102is: 103.Oo Ar clnt Oc : Ns Oo Ar srv Oc : Ns Ar access_list 104.Pp 105Allows remapping the group ID (gid) in the incoming request to some other gid. 106This effectively changes the identity of the user in the request to that of 107some other local user. 108.Pp 109For clients where the gid in the incoming request is 110.Ar clnt 111and the client matches the 112.Ar access_list , 113change the group ID to 114.Ar srv . 115If 116.Ar clnt 117is asterisk (*), all groups are mapped by this rule. 118If 119.Ar clnt 120is omitted, all unknown groups are mapped by this rule. 121If 122.Ar srv 123is set to -1, access is denied. 124If 125.Ar srv 126is omitted, the gid is mapped to UID_NOBODY. 127.Pp 128The particular 129.Ar mapping Ns s 130are separated in the 131.Sy gidmap Ns = 132option by tilde (~) and are evaluated in the specified order until a match is 133found. 134Both 135.Sy root Ns = 136and 137.Sy root_mapping Ns = 138options (if specified) are evaluated before the 139.Sy gidmap Ns = 140option. 141The 142.Sy gidmap Ns = 143option is skipped in the case where the client matches the 144.Sy root Ns = 145option. 146.Pp 147The 148.Sy gidmap Ns = 149option is evaluated before the 150.Sy anon Ns = 151option. 152.Pp 153This option is supported only for AUTH_SYS. 154.It Sy index Ns = Ns Ar file 155Load 156.Ar file 157rather than a listing of the directory containing this file when the 158directory is referenced by an NFS URL. 159.It Sy log Ns Oo = Ns Ar tag Oc 160Enables NFS server logging for the specified file system. 161The optional 162.Ar tag 163determines the location of the related log files. 164The 165.Ar tag 166is defined in 167.Pa /etc/nfs/nfslog.conf . 168If no 169.Ar tag 170is specified, the default values associated with the global tag in 171.Pa /etc/nfs/nfslog.conf 172are used. 173Support of NFS server logging is only available for NFS Version 2 and 174Version 3 requests. 175.It Sy nohide 176By default, if server exports two filesystems, one of which is mounted as a 177child of the other, NFS Version 2 and Version 3 clients must mount both 178filesystems explicitly in order to access them. 179If a client only mounts the parent, it will see an empty directory at the 180location where the other filesystem is mounted. 181.Pp 182Setting the 183.Sy nohide 184option on a filesystem causes it to no longer be hidden in this manner, and the 185client will be able to move from the parent filesystem to this one without 186noticing the change. 187However, some NFS clients or applications may not function correctly when 188this option is used. 189In particular, files on different underlying filesystems may appear to have 190the same inode numbers. 191The 192.Sy nohide 193option only applies to NFS Version 2 and Version 3 requests. 194.It Sy noaclfab 195By default, the NFS server will fabricate POSIX-draft style ACLs in response 196to ACL requests from NFS Version 2 or Version 3 clients accessing shared 197file systems that do not support POSIX-draft ACLs (such as ZFS). 198Specifying 199.Sy noaclfab 200disables this behavior. 201.It Sy none Ns = Ns Ar access_list 202Access is not allowed to any client that matches the access list. 203The exception is when the access list is an asterisk (*), in which case 204.Sy ro 205or 206.Sy rw 207can override 208.Sy none . 209.It Sy nosub 210Prevents clients from mounting subdirectories of shared directories. 211For example, if 212.Pa /export 213is shared with the 214.Sy nosub 215option on server 216.Qq fooey 217then a NFS client cannot do: 218.Bd -literal -offset indent 219mount -F nfs fooey:/export/home/mnt 220.Ed 221.Pp 222NFS Version 4 does not use the MOUNT protocol. 223The 224.Sy nosub 225option only applies to NFS Version 2 and Version 3 requests. 226.It Sy nosuid 227By default, clients are allowed to create files on the shared file system with 228the setuid or setgid mode enabled. 229Specifying 230.Sy nosuid 231causes the server file system to silently ignore any attempt to enable the 232setuid or setgid mode bits. 233.It Sy public 234Moves the location of the public file handle from root 235.Pa ( / ) 236to the exported directory for WebNFS-enabled browsers and clients. 237This option does not enable WebNFS service; WebNFS is always on. 238Only one file system per server may use this option. 239Any other option, including the 240.Sy ro Ns = Ns Ar list 241and 242.Sy rw Ns = Ns Ar list 243options can be included with the 244.Sy public 245option. 246.It Sy ro 247Sharing is read-only to all clients. 248.It Sy ro Ns = Ns Ar access_list 249Sharing is read-only to the clients listed in 250.Ar access_list ; 251overrides the 252.Sy rw 253suboption for the clients specified. 254See 255.Sx access_list 256below. 257.It Sy root Ns = Ns Ar access_list 258Only root users from the hosts specified in 259.Ar access_list 260have root access. 261See 262.Sx access_list 263below. 264By default, no host has root access, so root users are mapped to an anonymous 265user ID (see the 266.Sy anon Ns = Ns Ar uid 267option described above). 268Netgroups can be used if the file system shared is using UNIX authentication 269(AUTH_SYS). 270.It Sy root_mapping Ns = Ns Ar uid 271For a client that is allowed root access, map the root UID to the specified 272user id. 273.It Sy rw 274Sharing is read-write to all clients. 275.It Sy rw Ns = Ns Ar access_list 276Sharing is read-write to the clients listed in 277.Ar access_list ; 278overrides the 279.Sy ro 280suboption for the clients specified. 281See 282.Sx access_list 283below. 284.It Sy sec Ns = Ns Ar mode Ns Oo : Ns Ar mode Oc Ns ... 285Sharing uses one or more of the specified security modes. 286The 287.Ar mode 288in the 289.Sy sec Ns = Ns Ar mode 290option must be a mode name supported on the client. 291If the 292.Sy sec Ns = 293option is not specified, the default security mode used is AUTH_SYS. 294Multiple 295.Sy sec Ns = 296options can be specified on the command line, although each mode can appear 297only once. 298The security modes are defined in 299.Xr nfssec 7 . 300.Pp 301Each 302.Sy sec Ns = 303option specifies modes that apply to any subsequent 304.Sy window Ns = , 305.Sy rw , 306.Sy ro , 307.Sy rw Ns = , 308.Sy ro Ns = , 309and 310.Sy root Ns = 311options that are provided before another 312.Sy sec Ns = 313option. 314Each additional 315.Sy sec Ns = 316resets the security mode context, so that more 317.Sy window Ns = , 318.Sy rw , 319.Sy ro , 320.Sy rw Ns = , 321.Sy ro Ns = , 322and 323.Sy root Ns = 324options can be supplied for additional modes. 325.It Sy sec Ns = Ns Sy none 326If the option 327.Sy sec Ns = Ns Sy none 328is specified when the client uses AUTH_NONE, or if the client uses a security 329mode that is not one that the file system is shared with, then the credential 330of each NFS request is treated as unauthenticated. 331See the 332.Sy anon Ns = Ns Ar uid 333option for a description of how unauthenticated requests are handled. 334.It Sy secure 335This option has been deprecated in favor of the 336.Sy sec Ns = Ns Sy dh 337option. 338.It Sy uidmap Ns = Ns Ar mapping Ns Oo ~ Ns Ar mapping Oc Ns ... 339Where 340.Ar mapping 341is: 342.Oo Ar clnt Oc : Ns Oo Ar srv Oc : Ns Ar access_list 343.Pp 344Allows remapping the user ID (uid) in the incoming request to some other uid. 345This effectively changes the identity of the user in the request to that of 346some other local user. 347.Pp 348For clients where the uid in the incoming request is 349.Ar clnt 350and the client matches the 351.Ar access_list , 352change the user ID to 353.Ar srv . 354If 355.Ar clnt 356is asterisk (*), all users are mapped by this rule. 357If 358.Ar clnt 359is omitted, all unknown users are mapped by this rule. 360If 361.Ar srv 362is set to -1, access is denied. 363If 364.Ar srv 365is omitted, the uid is mapped to UID_NOBODY. 366.Pp 367The particular 368.Ar mapping Ns s 369are separated in the 370.Sy uidmap Ns = 371option by tilde (~) and are evaluated in the specified order until a match is 372found. 373Both 374.Sy root Ns = 375and 376.Sy root_mapping Ns = 377options (if specified) are evaluated before the 378.Sy uidmap Ns = 379option. 380The 381.Sy uidmap Ns = 382option is skipped in the case where the client matches the 383.Sy root Ns = 384option. 385.Pp 386The 387.Sy uidmap Ns = 388option is evaluated before the 389.Sy anon Ns = 390option. 391.Pp 392This option is supported only for AUTH_SYS. 393.It Sy window Ns = Ns Ar value 394When sharing with 395.Sy sec Ns = Ns Sy dh , 396set the maximum life time (in seconds) of the RPC request's credential (in the 397authentication header) that the NFS server allows. 398If a credential arrives with a life time larger than what is allowed, the NFS 399server rejects the request. 400The default value is 30000 seconds (8.3 hours). 401.El 402.El 403.Ss access_list 404The 405.Ar access_list 406argument is a colon-separated list whose components may be any number of the 407following: 408.Bl -tag -width "indented" 409.It Sy hostname 410The name of a host. 411With a server configured for DNS or LDAP naming in the nsswitch 412.Sy hosts 413entry, any hostname must be represented as a fully qualified DNS or LDAP name. 414.It Sy netgroup 415A netgroup contains a number of hostnames. 416With a server configured for DNS or LDAP naming in the nsswitch 417.Sy hosts 418entry, any hostname in a netgroup must be represented as a fully qualified DNS 419or LDAP name. 420.It Sy domain name suffix 421To use domain membership the server must use DNS or LDAP to resolve hostnames to 422IP addresses; that is, the 423.Sy hosts 424entry in the 425.Pa /etc/nsswitch.conf 426must specify 427.Sy dns 428or 429.Sy ldap 430ahead of 431.Sy nis 432since only DNS and LDAP return the full domain name of the host. 433Other name services like NIS cannot be used to resolve hostnames on the server 434because when mapping an IP address to a hostname they do not return domain 435information. 436For example, 437.Bd -literal -offset indent 438NIS 172.16.45.9 --> "myhost" 439.Ed 440.Pp 441and 442.Bd -literal -offset indent 443DNS or LDAP 172.16.45.9 --> "myhost.mydomain.example.com" 444.Ed 445.Pp 446The domain name suffix is distinguished from hostnames and netgroups by a 447prefixed dot. 448For example, 449.Bd -literal -offset indent 450rw=.mydomain.example.com 451.Ed 452.Pp 453A single dot can be used to match a hostname with no suffix. 454For example, 455.Bd -literal -offset indent 456rw=. 457.Ed 458.Pp 459matches 460.Qq mydomain 461but not 462.Qq mydomain.example.com . 463This feature can be used to match hosts resolved through NIS rather 464than DNS and LDAP. 465.It Sy network 466The network or subnet component is preceded by an at-sign (@). 467It can be either a name or a dotted address. 468If a name, it is converted to a dotted address by 469.Xr getnetbyname 3SOCKET . 470For example, 471.Bd -literal -offset indent 472=@mynet 473.Ed 474.Pp 475would be equivalent to: 476.Bd -literal -offset indent 477=@172.16 or =@172.16.0.0 478.Ed 479.Pp 480The network prefix assumes an octet-aligned netmask determined from the zeroth 481octet in the low-order part of the address up to and including the high-order 482octet, if you want to specify a single IP address (see below). 483In the case where network prefixes are not byte-aligned, the syntax allows a 484mask length to be specified explicitly following a slash (/) delimiter. 485For example, 486.Bd -literal -offset indent 487=@theothernet/17 or =@172.16.132/22 488.Ed 489.Pp 490where the mask is the number of leftmost contiguous significant bits in the 491corresponding IP address. 492.Pp 493When specifying individual IP addresses, use the same @ notation described 494above, without a netmask specification. 495For example: 496.Bd -literal -offset indent 497=@172.16.132.14 498.Ed 499.Pp 500Multiple, individual IP addresses would be specified, for example, as: 501.Bd -literal -offset indent 502root=@172.16.132.20:@172.16.134.20 503.Ed 504.El 505.Pp 506A prefixed minus sign (-) denies access to that component of 507.Ar access_list . 508The list is searched sequentially until a match is found that either grants or 509denies access, or until the end of the list is reached. 510For example, if host 511.Qq terra 512is in the 513.Qq engineering 514netgroup, then 515.Bd -literal -offset indent 516rw=-terra:engineering 517.Ed 518.Pp 519denies access to 520.Qq terra 521but 522.Bd -literal -offset indent 523rw=engineering:-terra 524.Ed 525.Pp 526grants access to 527.Qq terra . 528.Sh OPERANDS 529The following operands are supported: 530.Bl -tag -width "pathname" 531.It Sy pathname 532The pathname of the file system to be shared. 533.El 534.Sh FILES 535.Bl -tag -width "/etc/nfs/nfslog.conf" 536.It Pa /etc/dfs/fstypes 537list of system types, NFS by default 538.It Pa /etc/dfs/sharetab 539system record of shared file systems 540.It Pa /etc/nfs/nfslogtab 541system record of logged file systems 542.It Pa /etc/nfs/nfslog.conf 543logging configuration file 544.El 545.Sh EXIT STATUS 546.Ex -std 547.Sh EXAMPLES 548.Ss Example 1 Sharing A File System With Logging Enabled 549The following example shows the 550.Pa /export 551file system shared with logging enabled: 552.Bd -literal -offset indent 553share -o log /export 554.Ed 555.Pp 556The default global logging parameters are used since no tag identifier is 557specified. 558The location of the log file, as well as the necessary logging work 559files, is specified by the global entry in 560.Pa /etc/nfs/nfslog.conf . 561The 562.Xr nfslogd 8 563daemon runs only if at least one file system entry in 564.Pa /etc/dfs/dfstab 565is shared with logging enabled upon starting or rebooting the system. 566Simply sharing a file system with logging enabled from the command line does not 567start the 568.Xr nfslogd 8 . 569.Ss Example 2 Remap A User Coming From The Particular NFS Client 570The following example remaps the user with uid 571.Sy 100 572at client 573.Sy 10.0.0.1 574to user 575.Sy joe : 576.Bd -literal -offset indent 577share -o uidmap=100:joe:@10.0.0.1 /export 578.Ed 579.Sh SEE ALSO 580.Xr getnetbyname 3SOCKET , 581.Xr netgroup 5 , 582.Xr nfslog.conf 5 , 583.Xr acl 7 , 584.Xr attributes 7 , 585.Xr nfssec 7 , 586.Xr mount 8 , 587.Xr mountd 8 , 588.Xr nfsd 8 , 589.Xr nfslogd 8 , 590.Xr share 8 , 591.Xr unshare 8 592.Sh NOTES 593If the 594.Sy sec Ns = 595option is presented at least once, all uses of the 596.Sy window Ns = , 597.Sy rw , 598.Sy ro , 599.Sy rw Ns = , 600.Sy ro Ns = , 601and 602.Sy root Ns = 603options must come after the first 604.Sy sec Ns = 605option. 606If the 607.Sy sec Ns = 608option is not presented, then 609.Sy sec Ns = Ns Sy sys 610is implied. 611.Pp 612If one or more explicit 613.Sy sec Ns = 614options are presented, 615.Sy sys 616must appear in one of the options mode lists for accessing using the AUTH_SYS 617security mode to be allowed. 618For example: 619.Bd -literal -offset indent 620share -F nfs /var 621share -F nfs -o sec=sys /var 622.Ed 623.Pp 624grants read-write access to any host using AUTH_SYS, but 625.Bd -literal -offset indent 626share -F nfs -o sec=dh /var 627.Ed 628.Pp 629grants no access to clients that use AUTH_SYS. 630.Pp 631Unlike previous implementations of 632.Nm , 633access checking for the 634.Sy window Ns = , 635.Sy rw , 636.Sy ro , 637.Sy rw Ns = , 638and 639.Sy ro Ns = 640options is done per NFS request, instead of per mount request. 641.Pp 642Combining multiple security modes can be a security hole in situations where 643the 644.Sy ro Ns = 645and 646.Sy rw Ns = 647options are used to control access to weaker security modes. 648In this example, 649.Bd -literal -offset indent 650share -F nfs -o sec=dh,rw,sec=sys,rw=hosta /var 651.Ed 652.Pp 653an intruder can forge the IP address for 654.Qq hosta 655(albeit on each NFS request) to side-step the stronger controls of AUTH_DES. 656Something like: 657.Bd -literal -offset indent 658share -F nfs -o sec=dh,rw,sec=sys,ro /var 659.Ed 660.Pp 661is safer, because any client (intruder or legitimate) that avoids AUTH_DES only 662gets read-only access. 663In general, multiple security modes per share command should only be used in 664situations where the clients using more secure modes get stronger access than 665clients using less secure modes. 666.Pp 667If 668.Sy rw Ns = 669and 670.Sy ro Ns = 671options are specified in the same 672.Sy sec Ns = 673clause, and a client is in both lists, the order of the two options determines 674the access the client gets. 675If client 676.Qq hosta 677is in two netgroups, 678.Qq group1 679and 680.Qq group2 , 681in this example, the client would get read-only access: 682.Bd -literal -offset indent 683share -F nfs -o ro=group1,rw=group2 /var 684.Ed 685.Pp 686In this example 687.Qq hosta 688would get read-write access: 689.Bd -literal -offset indent 690share -F nfs -o rw=group2,ro=group1 /var 691.Ed 692.Pp 693If within a 694.Sy sec Ns = 695clause, both the 696.Sy ro 697and 698.Sy rw Ns = 699options are specified, for compatibility, the order of the options rule is not 700enforced. 701All hosts would get read-only access, with the exception to those in the 702read-write list. 703Likewise, if the 704.Sy ro Ns = 705and 706.Sy rw 707options are specified, all hosts get read-write access with the exceptions of 708those in the read-only list. 709.Pp 710The 711.Sy ro Ns = 712and 713.Sy rw Ns = 714options are guaranteed to work over UDP and TCP but may not work over other 715transport providers. 716.Pp 717The 718.Sy root Ns = 719option with AUTH_SYS is guaranteed to work over UDP and TCP but may not work 720over other transport providers. 721.Pp 722The 723.Sy root Ns = 724option with AUTH_DES is guaranteed to work over any transport provider. 725.Pp 726There are no interactions between the 727.Sy root Ns = 728option and the 729.Sy rw , 730.Sy ro , 731.Sy rw Ns = , 732and 733.Sy ro Ns = 734options. 735Putting a host in the root list does not override the semantics of the other 736options. 737The access the host gets is the same as when the 738.Sy root Ns = 739option is absent. 740For example, the following share command denies access to 741.Qq hostb : 742.Bd -literal -offset indent 743share -F nfs -o ro=hosta,root=hostb /var 744.Ed 745.Pp 746The following gives read-only permissions to 747.Qq hostb : 748.Bd -literal -offset indent 749share -F nfs -o ro=hostb,root=hostb /var 750.Ed 751.Pp 752The following gives read-write permissions to 753.Qq hostb : 754.Bd -literal -offset indent 755share -F nfs -o ro=hosta,rw=hostb,root=hostb /var 756.Ed 757.Pp 758If the file system being shared is a symbolic link to a valid pathname, the 759canonical path (the path which the symbolic link follows) is shared. 760For example, if 761.Pa /export/foo 762is a symbolic link to 763.Pa /export/bar , 764the following share command results in 765.Pa /export/bar 766as the shared pathname (and not 767.Pa /export/foo ) : 768.Bd -literal -offset indent 769share -F nfs /export/foo 770.Ed 771.Pp 772An NFS mount of 773.Lk server:/export/foo 774results in 775.Lk server:/export/bar 776really being mounted. 777.Pp 778This line in the 779.Pa /etc/dfs/dfstab 780file shares the 781.Pa /disk 782file system read-only at boot time: 783.Bd -literal -offset indent 784share -F nfs -o ro /disk 785.Ed 786.Pp 787The 788.Xr mountd 8 789process allows the processing of a path name that contains a symbolic link. 790This allows the processing of paths that are not themselves explicitly shared 791with 792.Nm . 793For example, 794.Pa /export/foo 795might be a symbolic link that refers to 796.Pa /export/bar 797which has been specifically shared. 798When the client mounts 799.Pa /export/foo 800the mountd processing follows the symbolic link and responds with the 801.Pa /export/bar . 802The NFS Version 4 protocol does not use the mountd processing and the client's 803use of 804.Pa /export/foo 805does not work as it does with NFS Version 2 and Version 3 and the client 806receives an error when attempting to mount 807.Pa /export/foo . 808.Pp 809The 810.Sy nohide 811option violates RFC 1094, 812.%T "Network File System Protocol Specification" 813and RFC 1813, 814.%T "NFS: Network File System Version 3 Protocol Specification" 815.Pp 816The 817.Sy nohide 818option is provided for compatibility with Linux NFS. 819