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