diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 3a2ab48e9..4eb9e9525 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,9 @@ +2014-12-06 Corinna Vinschen + + * cygwin.xsl (toc.section.depth): Set to 4. + * ntsec.xml: Revamp account mapping documentation to account for the + new db_home, db_shell, db_gecos settings. + 2014-12-05 Yaakov Selkowitz * new-features.xml (ov-new1.7.34): Document qsort_r and __bsd_qsort_r. diff --git a/winsup/doc/cygwin.xsl b/winsup/doc/cygwin.xsl index 157f6f2ed..99ec5d09c 100644 --- a/winsup/doc/cygwin.xsl +++ b/winsup/doc/cygwin.xsl @@ -8,6 +8,6 @@ - + diff --git a/winsup/doc/ntsec.xml b/winsup/doc/ntsec.xml index 2649398af..500f8b780 100644 --- a/winsup/doc/ntsec.xml +++ b/winsup/doc/ntsec.xml @@ -632,257 +632,6 @@ with uid/gid -1. -Cygwin user names, home dirs, login shells - - -Obviously, if you don't maintain passwd and -group files, you need to have a way to maintain the other -fields of a passwd entry as well. Three things come to mind: - - - - - - -You want to use a Cygwin username different from your Windows username. - - - -Note: This is only supported via /etc/passwd and -/etc/group files. A Cygwin username maintained in -the Windows user databases would require very costly (read: slow) search -operations. - - - - - -You want a home dir different from the default /home/$USER. - - - - - -You want to specify a different login shell than /bin/bash. - - - - - - -How this is done depends on your account being a domain account or a -local account. Let's start with the default. Assuming your Windows -account name is bigfoot and your domain is -MY_DOM. Your default passwd entry looks like this: - - - - bigfoot:*:<uid>:<gid>:U-MY_DOM\bigfoot,S-1-5-....:/home/bigfoot:/bin/bash - - - -or, if your account is from a different domain than the primary domain of -the machine: - - - - MY_DOM+bigfoot:*:<uid>:<gid>:U-MY_DOM\bigfoot,S-1-5-....:/home/bigfoot:/bin/bash - - - -Yes, the default homedir is still /home/bigfoot. - - - -If your account is a domain account: - - - - - - -Either create an /etc/passwd and/or -/etc/group file with entries for your account and tweak -that, - - - - - -or Cygwin will utilize the -posixAccount/posixGroup attributes per -RFC 2307. These -attributes are by default available in Active Directory since Windows Server -2003 R2. They are not set, unless utilized by the -(deprecated since Server 2012 R2) Active Directory "Server for NIS" feature. -The user attributes utilized by Cygwin are: - - - - - unixHomeDirectory - If set, will be used as Cygwin home directory. - - - loginShell - If set, will be used as Cygwin login shell. - - - gecos - Content will be added to the pw_gecos field. - - - uidNumber - See . - - - The group attributes utilized by Cygwin are: - - - gidNumber - See . - - - - -Apart from power shell scripting or inventing new CLI tools, these attributes -can be changed using the Attribute Editor tab in the user -properties dialog of the Active Directory Users and Computers -MMC snap-in. Alternatively, if the Server for NIS -administration feature has been installed, there will be a -UNIX Attributes tab which contains the required fields, -except for the gecos field, which isn't really important anyway. Last resort -is ADSI Edit. - - - -The primary group of a user is always the Windows primary group set in -Active Directory and can't be changed. - - - - - - -If your machine is not a domain member machine or your account is a -local account for some reason: - - - - - - -Either create an /etc/passwd and/or -/etc/group file with entries for your account and tweak -that, - - - - - -or enter the information into the comment field of your local user entry. -In the Local Users and Groups MMC snap-in it's called -Description. - - - -You can utilize this field even if you're running a "home edition" of -Windows, using the command line. The net user command -allows to set all values in the SAM, even if the GUI is crippled. - - - -A Cygwin SAM comment entry looks like this: - - - -<cygwin key="value" key="value" [...] /> - - - -The supported keys are: - - - - - home="value" - Sets the Cygwin home dir to value. - - - shell="value" - Sets the Cygwin login shell to value. - - - group="value" - Sets the Cygwin primary group of the account to value, provided that - the user *is* already a member of that group. This allows to override - the default "None" primary group for local accounts. One nice idea - here is, for instance group="Users". - - - unix="value" - Sets the NFS/Samba uid of the user to the decimal value. - See . - - - - -The <cygwin .../> string can start at any point in the comment, but -you have to follow the rules: - - - - -It starts with "<cygwin " and ends with "/>". - - -The "cygwin" string and the key names have to be lowercase. - - -No spaces between key and "value", just the equal sign. - - -The value must be placed within double quotes and it must not contain a double -quote itself. The double quotes are required for the decimal values as well! - - - - -CMD example: - - - -net user corinna /comment:"<cygwin home=\"/home/foo\"/>" - - - -Bash example (use single quotes): - - - -net user corinna /comment:'<cygwin home="/home/foo"/>' - - - -For changing group comments, use the `net localgroup' command. The supported -key/value pair for groups are: - - - - - unix="value" - Sets the NFS/Samba gid of the group to the decimal value. - See . - - - - - - - - - Caching account information @@ -979,151 +728,72 @@ will not impact the running instance, only future instances. -NFS account mapping +Cygwin user names, home dirs, login shells -Microsoft's NFS client does not map the uid/gid values on the NFS shares -to SIDs. There's no such thing as a (fake) security descriptor returned -to the application. Rather, via an undocumented API an application can -fetch RFC 1813 -compatible NFSv3 stat information from the share. This is what Cygwin is -using to show stat information for files on NFS shares. - - - -The problem is, while all other information in this stat record, like -timestamps, file size etc., can be used by Cygwin, Cygwin had no way to -map the values of the st_uid and st_gid members to a Windows SID for a -long time. So it just faked the file owner info and claimed that it's -you. - - - -However, SFU has, over time, developed multiple methods to map UNIX -uid/gid values on NFS shares to Windows SIDs. You'll find the full -documentation of the mapping methods in -NFS Identity Mapping in Windows Server 2012 - - - -Cygwin now utilizes the -RFC 2307 -mapping for this purpose. This is most of the time provided by an AD domain, -but it could also be a standalone LDAP mapping server. Per -RFC 2307, the uid is -in the attribute uidNumber. For groups, the gid is in the -gidNumber attribute. - - - -When Cygwin stat()s files on an NFS share, it asks the mapping server via -LDAP in two different ways, depending on the role of the mapping server. +Obviously, if you don't maintain passwd and +group files, you need to have a way to maintain the other +fields of a passwd entry as well. A couple of things come to mind: -If the server is an AD domain controller, it asks for an account with -uidNumber attribute == st_uid field of -the stat record returned by NFS. If an account matches, AD returns the -Windows SID, so we have an immediate mapping from UNIX uid to a Windows SID, -if the user account has a valid uidNumber attribute. For -groups, the method is the same, just that Cygwin asks for a group with -gidNumber attribute == st_gid field of the -stat record. + +You want to use a Cygwin username different from your Windows username. + + + +Note: This is only supported via /etc/passwd. A +Cygwin username maintained in the Windows user databases would require +very costly (read: slow) search operations. + -If the server is a standalone LDAP mapping server Cygwin asks for the -same uidNumber/gidNumber attributes, but -it can't expect that the LDAP server knows anything about Windows SIDs. -Rather, the mapping server returns the account name. Cygwin then asks the -DC for an account with this name, and if that succeeds, we have a mapping -between UNIX uid/gid and Windows SIDs. + +You want to change the primary group of a user. For AD accounts this is +not supported. The primary group of a user is always the Windows +primary group set in Active Directory and can't be changed. For SAM +accounts, you can add the primary group to the SAM +description field of the user. See for more info. + + + + + +You want a home dir different from the default +/home/$USERNAME. + + + + + +You want to specify a different login shell than /bin/bash. + + + + + +You want to add specific content to the pw_gecos field. + -The mapping will be cached for the lifetime of the process, and inherited -by child processes. - - - - -Samba account mapping - - -A fully set up Samba with domain integration is running winbindd to -map Window SIDs to artificially created UNIX uids and gids, and this -mapping is transparent within the domain, so Cygwin doesn't have to do -anything special. +For simple needs you can create /etc/passwd and/or +/etc/group files with entries for your account +and tweak that. -However, setting up winbindd isn't for everybody, and it fails to map -Windows accounts to already existing UNIX users or groups. In contrast -to NFS, Samba returns security descriptors, but unmapped UNIX accounts -get special SIDs: - - - - - -A UNIX user account with uid X is mapped to the Windows SID S-1-22-1-X. - - - -A UNIX group account with gid X is mapped to SID S-1-22-2-X. - - - - - -As you can see, even though we have SIDs, they just reflect the actual -uid/gid values on the UNIX box in the RID value. It's only marginally -different from the NFS method, so why not just use the same method as -for NFS? - - - -That's what Cygwin will do. If it encounters a S-1-22-x-y SID, it -will perform the same -RFC 2307 -mapping as for NFS shares. - - - -For home users without any Windows domain or LDAP server per -RFC 2307, -but with a Linux machine running Samba, just add this information to -your SAM account. Assuming the uid of your Linux user account is 505 -and the gid of your primary group is, say, 100, just add the values to -your SAM user and group accounts. The following example assumes you -didn't already add something else to the comment field. - - - -To your user's SAM comment (remember: called Description -in the GUI), -add: - - - - <cygwin group="Users" unix="505"/> - - - -To the user's group SAM comment add: - - - - <cygwin unix="100"/> - - - -This should be sufficient to work on your Samba share and to see -all files owned by your Linux user account as your files. +For bigger installations, maintaining per-client files is rather troublesome. +Also, no two environments are the same, so the needs are pretty different. +Therefore Cygwin supports configuring how to fetch home directory, +login shell, and gecos information in /etc/nsswitch.conf. See the next +section for detailed information how to configure Cygwin's account handling. @@ -1131,11 +801,9 @@ all files owned by your Linux user account as your files. The <filename>/etc/nsswitch.conf</filename> file -Last, but not least, let's talk about the way to configure how the -mapping works on your machine. On Linux and some other UNIXy OSes, we -have a file called +On Linux and some other UNIXy OSes, we have a file called /etc/nsswitch.conf. -One part of it is to specify how the passwd and group entries are generated. +Among other things, it determines how passwd and group entries are generated. That's what Cygwin now provides as well. @@ -1194,7 +862,7 @@ the old information. So, what settings can we perform with /etc/nsswitch.conf? -To explain, lets have a look into an /etc/nsswitch.conf +Let's start with an example /etc/nsswitch.conf file file set up to all default values: @@ -1205,9 +873,14 @@ file set up to all default values: - db_enum: cache builtin + db_enum: cache builtin + db_home: cygwin desc + db_shell: cygwin desc + db_gecos: cygwin desc +The <filename>/etc/nsswitch.conf</filename> syntax + The first line, starting with a hash # is a comment. The hash character starts a comment, just as in shell scripts. Everything @@ -1245,9 +918,9 @@ Apart from this restriction, the reminder of the line can have as many spaces and TABs as you like. - -Now let's have a look at the available keywords and settings. - + + +The <literal>passwd:</literal> and <literal>group:</literal> settings The two lines starting with the keywords passwd: and @@ -1304,13 +977,24 @@ Cygwin will always try the files first, then the db. -The remaining entries define certain aspects of the Windows account -database search. Right now, only one entry is valid: +passwd: and group: are the two basic +settings defining where to get the account information from. The following +settings starting with db_ define certain aspects of the +Windows account database search and how to generate passwd +and group information from the database. + + + - + +The <literal>db_enum:</literal> setting + db_enum: defines the depth of a database search, if an application calls one of the enumeration functions @@ -1497,8 +1185,8 @@ The recognized sources are the following: all - The opposite. Enumerates accounts from all known sources, including - all trusted domains. + The opposite. Enumerates accounts from all known sources, + including all trusted domains. cache @@ -1506,15 +1194,15 @@ The recognized sources are the following: builtin - Enumerate the predefined builtin accounts for backward compatibility. - These are five passwd accounts (SYSTEM, LocalService, NetworkService, - Administrators, TrustedInstaller) and two group accounts (SYSTEM and - TrustedInstaller). + Enumerate the predefined builtin accounts for backward + compatibility. These are five passwd accounts (SYSTEM, + LocalService, NetworkService, Administrators, TrustedInstaller) + and two group accounts (SYSTEM and TrustedInstaller). files Enumerate the accounts from /etc/passwd or - /etc/group. + /etc/group. local @@ -1531,11 +1219,11 @@ The recognized sources are the following: some.domain Enumerate all accounts from the trusted domain some.domain. The - trusted domain can be given as Netbios flat name (MY_DOMAIN) or as - dns domain name (my_domain.corp). In contrast to the aforementioned - fixed source keywords, distinct domain names are caseinsensitive. - Only domains which are actually trusted domains are enumerated. - Unknown domains are simply ignored. + trusted domain can be given as Netbios flat name (MY_DOMAIN) or + as dns domain name (my_domain.corp). In contrast to the + aforementioned fixed source keywords, distinct domain names are + caseinsensitive. Only domains which are actually trusted domains + are enumerated. Unknown domains are simply ignored. @@ -1600,12 +1288,833 @@ domain1.corp, sub.domain.corp and domain2.net. Enumerate everything and the kitchen sink. + + +Settings defining how to create the <literal>passwd</literal> entry + + +/etc/nsswitch.conf supports three settings to configure +where to get the pw_dir, pw_shell, and pw_gecos content of a +passwd entry from: + + + + db_home: schema... # Define how to fetch the pw_dir entry. + db_shell: schema... # Define how to fetch the pw_shell entry. + db_gecos: schema... # Define how to fetch the pw_gecos entry. + + +"schema..." is a list of up to four space-separated schemata: + + + db_FOO: schema1 schema2 ... + + + +When generating a passwd entry, Cygwin tries the schemata in order. If +the first schema returns an empty string, it skips to the second, and so +on. Schemata only supported on AD are silently skipped for SAM accounts +and on non-AD machines. + + + +Four schemata are predefined, two schemata are variable. The predefined +schemata are the following: + + + + + windows + Utilizes typical Windows settings. Supported for AD and SAM + accounts. + + + cygwin + Utilizes the cygwinUser AD schema extension. This schema + extension is available via a schema extension file + /usr/share/cygwin/cygwin.ldif. + See for + more information. + + + unix + Utilizes the posixAccount schema attributes per + RFC 2307. + The posixAccount schema is available by default since Windows + Server 2003 R2, but typically only utilized when installing the + Active Directory "Server for NIS" feature (which is deprecated + since Server 2012 R2). + See also . + + + + desc + Utilizes XML-style attributes in the description attribute. + Supported for AD and SAM accounts. + See + for a more detailed description. + + + + +The variable schemata are as follows. Note that the leading characters +(@ and /) are an integral part of the +definition. + + + + + @ad_attribute + ad_attribute is any arbitrary AD attribute + name which should (ideally) be available in the User class or + in any attached auxiliary class. It's always treated as a + single string argument. Only the first string of a multi-string + attributes will be read. + + + /path + An arbitrary string, typically a path. The leading slash is + required. Given that a single, fixed path for all users + only makes marginal sense, the /path schema supports wildcards. + A wildcard is a per-cent (%) character, + followed by another character giving the meaning. The supported + wildcard characters are: + + + + %u + The Cygwin username (that's lowercase + u). + + + %U + The Windows username (that's uppercase + U). + + + %D + Windows domain in NetBIOS style. + + + %_ + Since space and TAB characters are used to separate + the schemata, a space in the filename has to be + given as %_ (that's an + underscore). + + + %% + A per-cent character. + + + Any other %X expression is treated as if + the character X has been given alone. + + + + + +The exact meaning of a schema depends on the setting it's used for. The +following sections explain the settings in detail. + + + + +The <literal>db_home:</literal> setting + + +The db_home: setting defines how Cygwin fetches the user's +home directory, or, more precise, the content of the pw_dir +member of the user's passwd entry. The following list describes the meaning +of each schema when used with db_home: + + + + + windows + The user's home directory is set to the same directory which is + used as Windows home directory. This is the + homeDrive AD attribute if set, or the + homeDirectory AD attribute if + homeDrive is not set. For SAM accounts, + this is equivalent to the "Home folder" setting in SAM. + If both attributes are unset, Cygwin falls back to the user's + local profile directory, typically something along the lines + of C:\Users\$USERNAME. Of course, the + Windows directory is converted to POSIX-style by Cygwin. + + + + cygwin + AD only: The user's home directory is set to the POSIX path given + in the cygwinHome attribute from the + cygwinUser auxiliary class. + See also . + + + + unix + AD only: The user's home directory is set to the POSIX path given + in the unixHomeDirectory attribute from the + posixAccount auxiliary class. + See also . + + + + desc + The user's home directory is set to the POSIX path given in the + home="..." XML-alike setting in the user's + description attribute in SAM or AD. + See + for a detailed description. + + + @ad_attribute + AD only: The user's home directory is set to the path given + in the ad_attribute attribute. The path + can be given as Windows or POSIX path. + + + /path + The user's home directory is set to the given POSIX path. + Remember the wildcards described in + . + + + Fallback + If none of the schemes given for db_home: + define a non-empty directory, the user's home directory is set to + /home/$USERNAME. + + + + +As has been briefly mentioned before, the default setting for +db_home: is + + + + db_home: cygwin desc + + + +So, for AD accounts Cygwin tries to fetch the path from the user's +cygwinHome attribute first. If that's not available, +or if the account is a local SAM account, Cygwin tries to get the home +directory from the home= attribute of the user's +description field. If that's not available, Cygwin +falls back to the path /home/$USERNAME. + + + + +The <literal>db_shell:</literal> setting + + +The db_shell: setting defines how Cygwin fetches the user's +login shell, the content of the pw_shell member of the +user's passwd entry. The following list describes the meaning of each schema +when used with db_shell: + + + + + windows + The windows schema is ignored for now. + The logical choice would be CMD, but that introduces some + problems, for instance the fact that CMD has no concept of + running as login shell. This may change + in future. + + + cygwin + AD only: The user's home directory is set to the POSIX path given + in the cygwinShell attribute from the + cygwinUser auxiliary class. + See also . + + + + unix + AD only: The user's login shell is set to the POSIX path given + in the loginShell attribute from the + posixAccount auxiliary class. + See also . + + + + desc + The user's login shell is set to the POSIX path given in the + shell="..." XML-alike setting in the user's + description attribute in SAM or AD. + See + for a detailed description. + + + @ad_attribute + AD only: The user's login shell is set to the path given + in the ad_attribute attribute. The path + can be given as Windows or POSIX path. + + + /path + The user's login shell is set to the given POSIX path. + Albeit not being as important here, the wildcards described in + + are also available for specifying a login shell path. + + + Fallback + If none of the schemes given for db_shell: + define a non-empty pathname, the user's login shell is set to + /bin/bash. + + + + +As for db_home:, the default setting for +db_shell: is + + + + db_shell: cygwin desc + + + +So, for AD accounts Cygwin tries to fetch the path from the user's +cygwinShell attribute first. If that's not available, +or if the account is a local SAM account, Cygwin tries to get the home +directory from the shell= attribute of the user's +description field. If that's not available, Cygwin +falls back to /bin/bash. + + + + +The <literal>db_gecos:</literal> setting + + +The db_gecos: setting defines how to fetch additional +content for the pw_gecos member of the user's passwd entry. +There's always a fixed, Cygwin-specific part in the pw_gecos +field for identifying the account. However, an administrator might want to +add informative content like, for instance, the user's full name. That's +what the db_gecos: setting is for. +The following list describes the meaning of each schema when used with +db_gecos: + + + + + windows + Add the AD displayName attribute or, for + SAM accounts, the "Full name" entry to the + pw_gecos field. + + + cygwin + AD only: The content of the cygwinGecos + attribute from the cygwinUser auxiliary class + is added to pw_gecos. + See also . + + + + unix + AD only: The content of the gecos attribute + from the posixAccount auxiliary class + is added to pw_gecos. + See also . + + + + desc + The content of the gecos="..." XML-alike setting in the user's + description attribute in SAM or AD is added + to pw_gecos. + See + for a detailed description. + + + @ad_attribute + AD only: The content of the ad_attribute + attribute is added to pw_gecos. + + + /path + The string following the slash is added to + pw_gecos. Here, the wildcards described in + + may come in handy. + + + Fallback + If none of the schemes given for db_gecos: + define a non-empty pathname, nothing is added to + pw_gecos. + + + + +As for db_home: and db_shell:, the +default setting for db_gecos: is + + + + db_gecos: cygwin desc + + + +So, for AD accounts Cygwin tries to fetch the string from the user's +cygwinGecos attribute first. If that's not available, +or if the account is a local SAM account, Cygwin tries to get the home +directory from the gecos= attribute of the user's +description field. If that's not available, Cygwin +just doesn't add anything to pw_gecos. + + + + +The <literal>cygwin</literal> schema + + +The cygwin schema is based on a Cygwin-specific Active +Directory schema extension. Using this schema extension allows to maintain +Cygwin-specific settings entirely within AD, without colliding with any other +schema. + + + +The cygwin schema extension is available in a default Cygwin installation +in the file /usr/share/cygwin/cygwin.ldif. To install +the schema extension, you have to be schema admin, and you have to run the +ldifde command on the schema master. The installation +itself is rather simple. Assuming you're schema admin and running a shell +with administrative privileges: + + + + $ cd /usr/share/cygwin + $ ldifde -i -f cygwin.ldif -k -c "CN=schema,CN=Configuration,DC=X" #schemaNamingContext + + + +Afterwards, the auxiliary class cygwinUser is attached to +the class User, and the auxiliary class +cygwinGroup is attached to the class +Group. The new attributes can be immediately edited +using ADSI Edit. + + + +At the time of writing the following attributes are utilized by Cygwin: + + + + + cygwinHome + Used as Cygwin home directory with db_home: cygwin. + See . + + + cygwinShell + Used as Cygwin login shell with db_shell: cygwin. + See . + + + cygwinGecos + Content will be added to the pw_gecos field with + db_gecos: cygwin. + See . + + + + + + +The <literal>unix</literal> schema + + +The unix schema utilizes the +posixAccount attribute extension. This is one of two +schema extensions which are connected to AD accounts, available by default +starting with Windows Server 2003 R2. They are usually +not set, unless used by the Active Directory +Server for NIS feature (deprecated since Server 2012 R2). + +Two schemata are interesting for Cygwin, posixAccount, +connected to user accounts, and posixGroup, connected +to group accounts. Both follow the description of RFC 2307, +an Approach for Using LDAP as +a Network Information Service. +The user attributes utilized by Cygwin are: + + + + + unixHomeDirectory + Used as Cygwin home directory with db_home: unix. + See . + + + loginShell + Used as Cygwin login shell with db_shell: unix. + See . + + + gecos + Content will be added to the pw_gecos field with + db_gecos: unix. + See . + + + uidNumber + See and + . + + + + +The group attributes utilized by Cygwin are: + + + + + gidNumber + See and + . + + + + +Apart from power shell scripting or inventing new CLI tools, these attributes +can be changed using the Attribute Editor tab in the user +properties dialog of the Active Directory Users and Computers +MMC snap-in. Alternatively, if the Server for NIS +administration feature has been installed, there will be a +UNIX Attributes tab which contains the required fields, +except for the gecos field. Last resort is ADSI Edit. + + + + +The <literal>desc</literal> schema + + +When using user accounts from the local account database, the SAM, there +are only a very limited number of settings available. In contrast to +Active Directory there's no way to add fields to a user's entry. You have +to make do with the fields available. The method to utilize the +description field has been mainly introduced for those +accounts, usually the only ones a home user has. However, for symmetry, +and because there may be a reason to use this in an AD environment, this +schema is also supported for AD users. + + + + +The presentation of local user account settings on Windows is confusing, +to say the least. The description field is not visible at +all in the user settings available via the User Accounts +control settings. And while it's called Description in the +Local Users and Groups MMC snap-in (available, for instance, +via the Computer Management GUI), in the command +line tool net user the same field is called +comment. The latter is especially confusing for +AD admins, because the comment attribute in AD is called +usercomment on the command line. Confused? Never mind, +you're not the only one... + + + + +Fortunately you can utilize the description field even if +you're running a "home edition" of Windows, by using the command line. The +net user command allows to set all values in the SAM, even +if the GUI is crippled. + + + +A Cygwin SAM comment entry looks like this: + + + +<cygwin key="value" key="value" [...] /> + + + +The supported keys are: + + + + + home="value" + Sets the Cygwin home dir to value. + + + shell="value" + Sets the Cygwin login shell to value. + + + gecos="value" + Adds the string value to the user's gecos field. + + + + +The next two settings are only supported for SAM accounts. + + + + + group="value" + Sets the Cygwin primary group of the account to value, provided that + the user is already a member of that group. + This allows to override the default None primary + group for local accounts. One nice idea here is, for instance, + group="Users". + + + unix="value" + Sets the NFS/Samba uid of the user to the decimal value. + See and + . + + + + +The <cygwin .../> string can start at any point in the comment, but +you have to follow the rules: + + + + +It starts with "<cygwin " and ends with "/>". + + +The "cygwin" string and the key names have to be lowercase. + + +No spaces between key and "value", just the equal sign. + + +The value must be placed within double quotes and it must not contain a double +quote itself. The double quotes are required for the decimal values as well! + + + + + +There's also a length restriction imposed by Windows. The +description entry has a maximumn length of 1023 characters. + + + + +CMD example: + + + +net user corinna /comment:"<cygwin home=\"/home/foo\"/>" + + + +Bash example (use single quotes): + + + +net user corinna /comment:'<cygwin home="/home/foo"/>' + + + +For changing group comments, use the `net localgroup' command. The supported +key/value pair for SAM groups are: + + + + + unix="value" + Sets the NFS/Samba gid of the group to the decimal value. + See and + . + + + + + + + +NFS account mapping + + +Microsoft's NFS client does not map the uid/gid values on the NFS shares +to SIDs. There's no such thing as a (fake) security descriptor returned +to the application. Rather, via an undocumented API an application can +fetch RFC 1813 +compatible NFSv3 stat information from the share. This is what Cygwin is +using to show stat information for files on NFS shares. + + + +The problem is, while all other information in this stat record, like +timestamps, file size etc., can be used by Cygwin, Cygwin had no way to +map the values of the st_uid and st_gid members to a Windows SID for a +long time. So it just faked the file owner info and claimed that it's +you. + + + +However, SFU has, over time, developed multiple methods to map UNIX +uid/gid values on NFS shares to Windows SIDs. You'll find the full +documentation of the mapping methods in +NFS Identity Mapping in Windows Server 2012 + + + +Cygwin now utilizes the +RFC 2307 +mapping for this purpose. This is most of the time provided by an AD domain, +but it could also be a standalone LDAP mapping server. Per +RFC 2307, the uid is +in the attribute uidNumber. For groups, the gid is in the +gidNumber attribute. +See . + + + +When Cygwin stat()s files on an NFS share, it asks the mapping server via +LDAP in two different ways, depending on the role of the mapping server. + + + + + +If the server is an AD domain controller, it asks for an account with +uidNumber attribute == st_uid field of +the stat record returned by NFS. If an account matches, AD returns the +Windows SID, so we have an immediate mapping from UNIX uid to a Windows SID, +if the user account has a valid uidNumber attribute. For +groups, the method is the same, just that Cygwin asks for a group with +gidNumber attribute == st_gid field of the +stat record. + + + +If the server is a standalone LDAP mapping server Cygwin asks for the +same uidNumber/gidNumber attributes, but +it can't expect that the LDAP server knows anything about Windows SIDs. +Rather, the mapping server returns the account name. Cygwin then asks the +DC for an account with this name, and if that succeeds, we have a mapping +between UNIX uid/gid and Windows SIDs. + +The mapping will be cached for the lifetime of the process, and inherited +by child processes. + + +Samba account mapping + + +A fully set up Samba with domain integration is running winbindd to +map Window SIDs to artificially created UNIX uids and gids, and this +mapping is transparent within the domain, so Cygwin doesn't have to do +anything special. + + + +However, setting up winbindd isn't for everybody, and it fails to map +Windows accounts to already existing UNIX users or groups. In contrast +to NFS, Samba returns security descriptors, but unmapped UNIX accounts +get special SIDs: + + + + + +A UNIX user account with uid X is mapped to the Windows SID S-1-22-1-X. + + + +A UNIX group account with gid X is mapped to SID S-1-22-2-X. + + + + + +As you can see, even though we have SIDs, they just reflect the actual +uid/gid values on the UNIX box in the RID value. It's only marginally +different from the NFS method, so why not just use the same method as +for NFS? + + + +That's what Cygwin will do. If it encounters a S-1-22-x-y SID, it +will perform the same +RFC 2307 +mapping as for NFS shares. + + + +For home users without any Windows domain or LDAP server per +RFC 2307, +but with a Linux machine running Samba, just add this information to +your SAM account. Assuming the uid of your Linux user account is 505 +and the gid of your primary group is, say, 100, just add the values to +your SAM user and group accounts. The following example assumes you +didn't already add something else to the comment field. + + + +To your user's SAM comment (remember: called Description +in the GUI), +add: + + + + <cygwin group="Users" unix="505"/> + + + +To the user's group SAM comment add: + + + + <cygwin unix="100"/> + + + +This should be sufficient to work on your Samba share and to see +all files owned by your Linux user account as your files. + + +