<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<sect1 id="ntsec"><title>Using Windows security in Cygwin</title>
+<sect1 id="ntsec"><title>POSIX accounts, permission, and security</title>
<para>This section discusses how the Windows security model is
-utilized in Cygwin to implement POSIX-like permissions, as well as how
-the Windows authentication model is used to allow cygwin applications
-to switch users in a POSIX-like fashion.</para>
+utilized in Cygwin to implement POSIX account information, POSIX-like
+permissions, and how the Windows authentication model is used to allow
+cygwin applications to switch users in a POSIX-like fashion.</para>
<para>The setting of POSIX-like file and directory permissions is
controlled by the <link linkend="mount-table">mount</link> option
don't know the POSIX security model, search the web for beginner
documentation.</para>
-<sect2 id="ntsec-common"><title>Overview</title>
+<sect2 id="ntsec-common"><title>Brief overview of Windows security</title>
<para>In the Windows security model, almost any "object" is securable.
"Objects" are files, processes, threads, semaphores, etc.</para>
"FOO\johndoe", the other one is "BAR\johndoe" or "johndoe@bar.local".
Different SID, different account. Full stop. </para>
-<para>The last part of the SID, the so called "Relative IDentifier" (RID),
-is by default used as UID and/or GID under Cygwin when you create the
-<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
-files using the <command><link linkend="mkpasswd">mkpasswd</link></command> and <command><link linkend="mkgroup">mkgroup</link></command>
-tools. Domain account UIDs and GIDs are offset by 10000 by default
-which might be a bit low for very big organizations. Fortunately there's
-an option in both tools to change the offset...</para>
+<para>Starting with Cygwin 1.7.32, Cygwin uses an automatic, internal
+translation from Windows SID to POSIX UID/GID. This mechanism, which is
+the preferred method for the SID<=>UID/GID mapping, is described in
+detail in <xref linkend="ntsec-mapping"></xref>.</para>
+
+<para>Up to Cygwin 1.7.31, the last part of the SID, the so called
+"Relative IDentifier" (RID), was by default used as UID and/or GID
+when you created the <filename>/etc/passwd</filename> and
+<filename>/etc/group</filename> files using the
+<command><link linkend="mkpasswd">mkpasswd</link></command> and
+<command><link linkend="mkgroup">mkgroup</link></command> tools.
+These tools as well as reading accounts from <filename>/etc/passwd</filename>
+and <filename>/etc/group</filename> files is still present in recent
+versions of Cygwin, but you should switch to the aforementioned
+automatic translation, unless you have very specific needs. Again,
+see <xref linkend="ntsec-mapping"></xref> for the details.</para>
<para>Do you still remember the SIDs with special meaning? In offical
notation they are called "well-known SIDs". For example, POSIX has no GID
</sect2>
-<sect2 id="ntsec-files"><title id="ntsec-files.title">File permissions</title>
+<sect2 id="ntsec-mapping"><title id="ntsec-mapping.title">Mapping Windows accounts to POSIX accounts</title>
+
+<para>
+For as long as Cygwin has existed, it has stored user and group information in
+<filename>/etc/passwd</filename> and <filename>/etc/group</filename> files.
+Under the assumption that these files would never be too large, the first
+process in a process tree, as well as every execing process within the tree
+would parse them into structures in memory. Thus every Cygwin process would
+contain an expanded copy of the full information from
+<filename>/etc/passwd</filename> and <filename>/etc/group</filename>.
+</para>
+
+<para>
+This approach has a few downsides. One of them is that the idea to have
+always small files is flawed. Another one is that reading the entire
+file is most of the time entirely useless, since most processes only
+need information on their own user and the primary group. Last but not
+least, the passwd and group files have to be maintained separately from
+the already existing Windows user databases, the local SAM and Active
+Directory.
+</para>
+
+<para>
+On the other hand, we have to have this mapping between Windows SIDs and
+POSIX uid/gid values, so we rely on some mechanism to convert SIDs to uid/gid
+values and vice versa.
+</para>
+
+<para>
+Microsoft "Services for UNIX" (SFU) (deprecated since Windows 8/Server 2012)
+never used passwd/group files. Rather, SFU used a fixed, computational mapping
+between SIDs and POSIX uid/gid which even has Active Directory support. It
+allows to generate uid/gid values from SIDs and vice versa. The mechanism is
+documented, albeit in a confusing way and spread over multiple MSDN articles.
+</para>
+
+<para>
+Starting with Cygwin 1.7.32, Cygwin utilizes an approach inspired by the
+mapping method as implemented by SFU, with a few differences for backward
+compatibility and to handle some border cases differently.
+</para>
+
+<sect3 id="ntsec-mapping-how"><title id="ntsec-mapping-how.title">Mapping Windows SIDs to POSIX uid/gid values</title>
+
+<para>
+The following description assumes you're comfortable with the concept of
+Windows SIDs and RIDs. For a brief introduction, see
+<xref linkend="ntsec-common"></xref>.
+</para>
+
+<para>
+Cygwin's mapping between SIDs and uid/gid values works in two ways.
+</para>
+
+<itemizedlist spacing="compact">
+<listitem><para>Read <filename>/etc/passwd<filename> and
+</filename>/etc/group</filename> files, just as in the olden days, mainly for
+backward compatibility.</para></listitem>
+<listitem><para>If no files are present, or if an entry is missing in the files,
+ask Windows.</para></listitem>
+</itemizedlist>
+
+<para>
+At least, that's the default behaviour now. It will be configurable
+using a file <filename>/etc/nsswitch.conf</filename>, which is discussed in
+<xref linkend="ntsec-mapping-nsswitch"></xref>. Let's explore the default
+for now.
+</para>
+
+<para>
+If files are present, they will be scanned on demand as soon as a
+mapping from SIDs to uid/gid or account names is required. The new
+mechanism will never read the entire file into memory, but only scan for
+the requested entry and cache this one in memory.
+</para>
+
+<para>
+If no entry is found, or no passwd or group file was present, Cygwin
+will ask the OS.
+</para>
+
+<note>
+<para>
+If the first process in a Cygwin process tree determines that no
+<filename>/etc/passwd</filename> or <filename>/etc/group</filename> file is
+present, no other process in the entire process tree will try to read the files
+later on. This is done for self-preservation. It's rather bad if the uid
+or gid of a user changes during the lifetime of a process tree.
+</para>
+
+<para>
+For the same reason, if you delete the <filename>/etc/passwd</filename>
+or <filename>/etc/group</filename> file, this will be ignored. The passwd
+and group records read from the files will persist in memory until either a
+new <filename>/etc/passwd</filename> or <filename>/etc/group</filename>
+is created, or you exit all processes in the current process tree.
+</para>
+
+<para>
+See the note in <xref linkend="ntsec-mapping-nsswitch"></xref> for some
+comprehensive examples.
+</para>
+</note>
+
+<para>
+So if we've drawn a blank reading the files, we're going to ask the OS.
+First thing, we ask the local machine for the SID or the username. The
+OS functions
+<ulink url="http://msdn.microsoft.com/en-us/library/windows/desktop/aa379166%28v=vs.85%29.aspx">LookupAccountSid</ulink>
+and
+<ulink url="http://msdn.microsoft.com/en-us/library/windows/desktop/aa379159%28v=vs.85%29.aspx">LookupAccountName</ulink>
+are pretty intelligent. They have all the stuff built in to ask for any
+account of the local machine, the Active Directory domain of the machine,
+the Global Catalog of the forest of the domain, as well as any trusted
+domain of our forest for the information. One OS call and we're
+practically done...
+</para>
+
+<para>
+Except, the calls only return the mapping between SID, account name and the
+account's domain. We don't have a mapping to POSIX uid/gid and we're missing
+information on the user's home dir and login shell.
+</para>
+
+<para>
+Let's discuss the SID<=>uid/gid mapping first. Here's how it works.
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+<para>
+<ulink url="http://msdn.microsoft.com/en-us/library/aa379649.aspx">Well-known
+SIDs</ulink>
+in the NT_AUTHORITY domain of the S-1-5-RID type, or aliases of the
+S-1-5-32-RID type are mapped to the uid/gid value RID. Examples:
+</para>
+
+<screen>
+ "SYSTEM" S-1-5-18 <=> uid/gid: 18
+ "Users" S-1-5-32-545 <=> uid/gid: 545
+</screen>
+</listitem>
+
+<listitem>
+<para>
+Other well-known SIDs in the NT_AUTHORITY domain (S-1-5-X-RID):
+</para>
+
+<screen>
+ S-1-5-X-RID <=> uid/gid: 0x1000 * X + RID
+</screen>
+
+<para>Example:</para>
+
+<screen>
+ "NTLM Authentication" S-1-5-64-10 <=> uid/gid: 0x4000A == 262154
+</screen>
+</listitem>
+
+<listitem><para>
+Other well-known SIDs:
+</para>
+
+<screen>
+ S-1-X-Y <=> uid/gid: 0x10000 + 0x100 * X + Y
+</screen>
+
+<para>Example:</para>
+
+<screen>
+ "LOCAL" S-1-2-0 <=> uid/gid: 0x10200 == 66048
+ "Creator Group" S-1-3-1 <=> uid/gid: 0x10301 == 66305
+</screen>
+</listitem>
+
+<listitem>
+<para>
+Logon SIDs: The own LogonSid is converted to the fixed uid 0xfff == 4095 and
+named "CurrentSession". Any other LogonSid is converted to the fixed uid
+0xffe == 4094 and named "OtherSession".
+</para>
+</listitem>
+
+<listitem>
+<para>
+Mandatory Labels:
+</para>
+
+<screen>
+ S-1-16-RID <=> uid/gid: 0x60000 + RID
+</screen>
+
+<para>Example:</para>
+
+<screen>
+ "Medium Mandatory Level" S-1-16-8192 <=> uid/gid: 0x62000 == 401408
+</screen>
+</listitem>
+
+<listitem>
+<para>
+Accounts from the local machine's user DB (SAM):
+</para>
+
+<screen>
+ S-1-5-21-X-Y-Z-RID <=> uid/gid: 0x30000 + RID
+</screen>
+
+<para>Example:</para>
+
+<screen>
+ "Administrator" S-1-5-21-X-Y-Z-500 <=> uid/gid: 0x301f4 == 197108
+</screen>
+</listitem>
+
+<listitem>
+<para>
+Accounts from the machine's primary domain:
+</para>
+
+<screen>
+ S-1-5-21-X-Y-Z-RID <=> uid/gid: 0x100000 + RID
+</screen>
+
+<para>Example:</para>
+
+<screen>
+ "Domain Users" S-1-5-21-X-Y-Z-513 <=> uid/gid: 0x100201 == 1049089
+</screen>
+</listitem>
+
+<listitem>
+<para>
+Accounts from a trusted domain of the machine's primary domain:
+</para>
+
+<screen>
+ S-1-5-21-X-Y-Z-RID <=> uid/gid: trustPosixOffset(domain) + RID
+</screen>
+
+<para>
+<literal>trustPosixOffset</literal>? This needs a bit of explanation. This
+value exists in Windows domains already since before Active Directory days.
+What happens is this. If you create a domain trust between two domains, a
+trustedDomain entry will be added to both databases. It describes how
+<emphasis>this</emphasis> domain trusts the <emphasis>other</emphasis> domain.
+One attribute of a trust is a 32 bit value called
+<literal>trustPosixOffset</literal> For each new trust,
+<literal>trustPosixOffset</literal> will get some automatic value. In recent
+AD domain implementations, the first trusted domain will get
+<literal>trustPosixOffset</literal> set to 0x80000000. Following domains will
+get lower values. Unfortunately the domain admins are allowed to set the
+<literal>trustPosixOffset</literal> value for each trusted domain to some
+arbitrary 32 bit value, no matter what the other
+<literal>trustPosixOffset</literal> are set to, thus allowing any kind of
+collisions between the <literal>trustPosixOffset</literal> values of domains.
+That's not exactly helpful, but as the user of this value, we have to
+<emphasis>trust</emphasis> the domain admins to set
+<literal>trustPosixOffset</literal> to sensible values, or to keep it at the
+system chosen defaults.
+</para>
+
+<para>
+So, for the first (or only) trusted domain of your domain, the automatic offset
+is 0x80000000. An example for a user of that trusted domain is
+</para>
+
+<screen>
+ S-1-5-21-X-Y-Z-1234 <=> uid/gid 0x800004d2 == 2147484882
+</screen>
+
+<para>
+There's one problem with this approach. Assuming you're running in the context
+of a local SAM user on a domain member machine. Local users don't have the
+right to fetch this kind of domain information from the DC, they'll get
+permission denied. In this case Cygwin will fake a sensible
+<literal>trustPosixOffset</literal> value.
+</para>
+
+<para>
+Another problem is if the AD administrators chose an unreasonable small
+<literal>trustPosixOffset</literal> value. Anything below the hexadecimal
+value 0x100000 (the POSIX offset of the primary domain) is bound to produce
+collisions with system accounts as well as local accounts. The right thing
+to do in this case is to notify your administrator of the problem and to ask
+for moving the offset to a more reasonable value. However, to reduce the
+probability for collisions, Cygwin overrides this offset with a sensible
+fixed replacement offset.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Local accounts from another machine in the network:
+</para>
+
+<para>
+There's no SID<=>uid/gid mapping implemented for this case. The problem
+is, there's no way to generate a bijective mapping. There's no central place
+which keeps an analogue value of the <literal>trustPosixOffset</literal>, and
+there's the additional problem that the
+<ulink url="http://msdn.microsoft.com/en-us/library/windows/desktop/aa379166%28v=vs.85%29.aspx">LookupAccountSid</ulink>
+and
+<ulink url="http://msdn.microsoft.com/en-us/library/windows/desktop/aa379159%28v=vs.85%29.aspx">LookupAccountName</ulink>
+functions cannnot resolve the SIDs, unless they know the name of the machine
+this SID comes from. And even then it will probably suffer a
+"Permission denied" when trying to ask the machine for its local account.
+</para>
+
+<para>
+Cygwin will map the account to the fake accounts "Unknown+User"/"Unknown+Group"
+with uid/gid -1.
+</para>
+</listitem>
+
+</itemizedlist>
+
+<para>
+Now we have a semi-bijective mapping between SIDs and POSIX uid/gid values,
+but given that we have potentially users and groups in different domains having
+the same name, how do we uniquely differ between them by name? Well, we can do
+that by making their names unique in a per-machine way. Dependent on the
+domain membership of the account, and dependent of the machine being a domain
+member or not, the user and group names will be generated using a domain prefix
+and a separator character between domain and account name. The default
+separator character is the plus sign, <literal>+</literal>.
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+<para>
+Well-known SIDs will have the separator character prepended:
+</para>
+
+<screen>
+ "+SYSTEM", "+LOCAL", "+Medium Mandatory Level", ...
+</screen>
+</listitem>
+
+<listitem>
+<para>
+If the machine is no domain member machine, only local accounts can be resolved
+into names, so for ease of use, just the account names are used as Cygwin
+user/group names:
+</para>
+
+<screen>
+ "corinna", "bigfoot", "None", ...
+</screen>
+</listitem>
+
+<listitem>
+<para>
+If the machine is a domain member machine, all accounts from the primary domain
+of the machine are mapped to Cygwin names without domain prefix:
+</para>
+
+<screen>
+"corinna", "bigfoot", "Domain Users", ...
+</screen>
+
+<para>
+while accounts from other domains are prepended by their domain:
+</para>
+
+<screen>
+ "DOMAIN1+corinna", "DOMAIN2+bigfoot", "DOMAIN3+Domain Users", ...
+</screen>
+</listitem>
+
+<listitem>
+<para>
+Local machine accounts of a domain member machine get a Cygwin user name the
+same way as accounts from another domain: The local machine name gets
+prepended:
+</para>
+
+<screen>
+ "MYMACHINE+corinna", "MYMACHINE+bigfoot", "MYMACHINE+None", ...
+</screen>
+</listitem>
+
+<listitem>
+<para>
+If LookupAccountSid fails, Cygwin checks the accounts against the known trusted
+domains. If the account is from one of the trusted domains, an artificial
+account name is created. It consists of the domain name, and a special name
+created from the account RID:
+</para>
+
+<screen>
+ "MY_DOM+User(1234)", "MY_DOM+Group(5678)"
+</screen>
+
+<para>
+Otherwise we know nothing about this SID, so it will be mapped to the
+fake accounts "Unknown+User"/"Unknown+Group" with uid/gid -1.
+</para>
+</listitem>
+
+</itemizedlist>
+
+</sect3>
+
+<sect3 id="ntsec-mapping-passwdinfo"><title id="ntsec-mapping-passwdinfo.title">Cygwin user names, home dirs, login shells</title>
+
+<para>
+Obviously, if you don't maintain <filename>passwd</filename> and
+<filename>group</filename> files, you need to have a way to maintain the other
+fields of a passwd entry as well. Three things come to mind:
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+<para>
+You want to use a Cygwin username different from your Windows username.
+</para>
+
+<note><para>
+Note: This is only supported via <filename>/etc/passwd</filename> and
+<filename>/etc/group</filename> files. A Cygwin username maintained in
+the Windows user databases would require very costly (read: slow) seach
+operations.
+</para></note>
+</listitem>
+
+<listitem>
+<para>
+You want a home dir different from the default <filename>/home/$USER</filename>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+You want to specify a different login shell than <filename>/bin/bash</filename>.
+</para>
+</listitem>
+
+</itemizedlist>
+
+<para>
+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 in absence of anything I'll describe below looks like this:
+</para>
+
+<screen>
+ bigfoot:*:<uid>:<gid>:U-MY_DOM\bigfoot,S-1-5-....:/home/bigfoot:/bin/bash
+</screen>
+
+<para>
+or, if your account is from a different domain than the primary domain of
+the machine:
+</para>
+
+<screen>
+ MY_DOM+bigfoot:*:<uid>:<gid>:U-MY_DOM\bigfoot,S-1-5-....:/home/bigfoot:/bin/bash
+</screen>
+
+<para>
+Yes, the default homedir is still /home/bigfoot.
+</para>
+
+<para>
+If your account is a domain account:
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+<para>
+Either create an <filename>/etc/passwd</filename> and/or
+<filename>/etc/group</filename> file with entries for your account and tweak
+that,
+</para>
+</listitem>
+
+<listitem>
+<para>
+or Cygwin will utilize the
+<literal>posixAccount</literal>/<literal>posixGroup</literal> attributes per
+<ulink url="https://tools.ietf.org/html/rfc2307">RFC 2307</ulink>. 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:
+</para>
+
+<segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>unixHomeDirectory</literal></seg>
+ <seg>If set, will be used as Cygwin home directory.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>loginShell</literal></seg>
+ <seg>If set, will be used as Cygwin login shell.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>gecos</literal></seg>
+ <seg>Content will be added to the pw_gecos field.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>uidNumber</literal></seg>
+ <seg>See <xref linkend="ntsec-mapping-nfs"></xref>.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>The group attributes utilized by Cygwin are:</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>gidNumber</literal></seg>
+ <seg>See <xref linkend="ntsec-mapping-nfs"></xref>.</seg>
+ </seglistitem>
+</segmentedlist>
+
+<para>
+Apart from power shell scripting or inventing new CLI tools, these attributes
+can be changed using the <literal>Attribute Editor</literal> tab in the user
+properties dialog of the <literal>Active Directory Users and Computers</literal>
+MMC snap-in. Alternatively, if the <literal>Server for NIS</literal>
+administration feature has been installed, there will be a
+<literal>UNIX Attributes</literal> tab which contains the required fields,
+except for the gecos field, which isn't really important anyway. Last resort
+is <literal>ADSI Edit</literal>.
+</para>
+
+<para>
+The primary group of a user is always the Windows primary group set in
+Active Directory and can't be changed.
+</para>
+</listitem>
+
+</itemizedlist>
+
+<para>
+If your machine is not a domain member machine or your account is a
+local account for some reason:
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+<para>
+Either create an <filename>/etc/passwd</filename> and/or
+<filename>/etc/group</filename> file with entries for your account and tweak
+that,
+</para>
+</listitem>
+
+<listitem>
+<para>
+or enter the information into the "Comment" field of your local user entry.
+In the <literal>Local Users and Groups</literal> MMC snap-in it's called
+<literal>Description</literal>.
+</para>
+
+<para>
+You can utilze this field even if you're running a "home edition" of
+Windows, using the command line. The <command>net user</command> command
+allows to set all values in the SAM, even if the GUI is crippled.
+</para>
+
+<para>
+A Cygwin SAM comment entry looks like this:
+</para>
+
+<screen>
+<cygwin key="value" key="value" [...] />
+</screen>
+
+<para>
+The supported keys are:
+</para>
+
+<segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>home="value"</literal></seg>
+ <seg>Sets the Cygwin home dir to value.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>shell="value"</literal></seg>
+ <seg>Sets the Cygwin login shell to value.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>group="value"</literal></seg>
+ <seg>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".</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>unix="value"</literal></seg>
+ <seg>Sets the NFS/Samba uid of the user to the decimal value.
+ See <xref linkend="ntsec-mapping-nfs"></xref>.</seg>
+ </seglistitem>
+</segmentedlist>
+
+<para>
+The <cygwin .../> string can start at any point in the comment, but
+you have to follow the rules:
+</para>
+
+<itemizedlist spacing="compact">
+<listitem>
+It starts with "<cygwin " and ends with "/>".
+</listitem>
+<listitem>
+The "cygwin" string and the key names have to be lowercase.
+</listitem>
+<listitem>
+No spaces between key and "value", just the equal sign.
+</listitem>
+<listitem>
+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!
+</listitem>
+</itemizedlist>
+
+<para>
+CMD example:
+</para>
+
+<screen>
+net user corinna /comment:"<cygwin home=\"/home/foo\"/<"
+</screen>
+
+<para>
+Bash example (use single quotes):
+</para>
+
+<screen>
+net user corinna /comment:'<cygwin home="/home/foo"/>'
+</screen>
+
+<para>
+For changing group comments, use the `net localgroup' command. The supported
+key/value pair for groups are:
+</para>
+
+<segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>unix="value"</literal></seg>
+ <seg>Sets the NFS/Samba gid of the group to the decimal value.
+ See <xref linkend="ntsec-mapping-nfs"></xref>.</seg>
+ </seglistitem>
+</segmentedlist>
+
+</listitem>
+
+</itemizedlist>
+
+</sect3>
+
+<sect3 id="ntsec-mapping-caching"><title id="ntsec-mapping-caching.title">Caching account information</title>
+
+<para>
+The information fetched from file or the Windows account database is cached
+by the process. The cached information is inherited by child processes.
+</para>
+
+<para>
+While usually working fine, this has some drawbacks. Consider a shell calling
+<command>id</command>. <command>id</command> fetches all group information
+from the current token and caches them. Unfortunately <command>id</command>
+doesn't start any child processes, so the information is lost as soon as
+<command>id</command> exits.
+</para>
+
+<para>
+But there's another caching mechanism available. If
+<command><link linkend="using-cygserver">cygserver</link></command> is running
+it will provide passwd and group entry caching for all processes in a Cygwin
+process tree, which first process has been started after
+<command><link linkend="using-cygserver">cygserver</link></command>. So, if
+you start a Cygwin Terminal and
+<command><link linkend="using-cygserver">cygserver</link></command> is running
+at the time, <command>mintty</command>, the shell, and all child processes will
+use <command><link linkend="using-cygserver">cygserver</link></command> caching.
+If you start a Cygwin Terminal and
+<command><link linkend="using-cygserver">cygserver</link></command> is not
+running a the time, none of the processes started inside this terminal window
+will use <command><link linkend="using-cygserver">cygserver</link></command>
+caching.
+</para>
+
+<para>
+The advantage of
+<command><link linkend="using-cygserver">cygserver</link></command> caching is
+that it's system-wide and, as long as
+<command><link linkend="using-cygserver">cygserver</link></command> is running,
+unforgetful. Every Cygwin process on the system will have the
+<command><link linkend="using-cygserver">cygserver</link></command> cache at
+its service. Additionally, all information requested from
+<command><link linkend="using-cygserver">cygserver</link></command> once, will
+be cached inside the process itself and, again, propagated to child processes.
+</para>
-<para>On NTFS and if the <literal>noacl</literal> mount option is not
-specified for a mount point, Cygwin sets file permissions as in POSIX.
-Basically this is done by defining a SD with the matching owner and group
-SIDs, and a DACL which contains ACEs for the owner, the group and for
-"Everyone", which represents what POSIX calls "others".</para>
+</sect3>
-<para>To use Windows security correctly, Cygwin depends on the files
-<filename>/etc/passwd</filename> and <filename>/etc/group</filename>.
-These files define the translation between the Cygwin uid/gid and the
-Windows SID. The SID is stored in the pw_gecos field in
-<filename>/etc/passwd</filename>, and in the gr_passwd field in
-<filename>/etc/group</filename>. Since the pw_gecos field can contain
-more information than just a SID, there are some rules for the layout.
-It's required that the SID is the last entry of the pw_gecos field,
-assuming that the entries in pw_gecos are comma-separated. The
-commands <command>mkpasswd</command> and <command>mkgroup</command>
-usually do this for you.</para>
-
-<para>Another interesting entry in the pw_gecos field (which is also
-usually created by running <command>mkpasswd</command>) is the Windows user
-name entry. It takes the form "U-domain\username" and is sometimes used
-by services to authenticate a user. Logging in through
-<command>telnet</command> is a common scenario.</para>
-
-<para>A typical snippet from <filename>/etc/passwd</filename>:</para>
-
-<example id="ntsec-passwd">
-<title>/etc/passwd:</title>
-<screen>
-SYSTEM:*:18:544:,S-1-5-18::
-Administrators:*:544:544:,S-1-5-32-544::
-Administrator:unused:500:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
-corinna:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
-</screen>
-</example>
-
-<para>The SYSTEM entry is usually needed by services. The Administrators
-entry (Huh? A group in /etc/passwd?) is only here to allow
-<command>ls</command> and similar commands to print some file ownerships
-correctly. Windows doesn't care if the owner of a file is a user or a
-group. In older versions of Windows NT the default ownership for files
-created by an administrator account was set to the group Administrators
-instead of to the creating user account. This has changed, but you can
-still switch to this setting on newer systems. So it's convenient to
-have the Administrators group in
-<filename>/etc/passwd</filename>.</para>
-
-<para>The really interesting entries are the next two. The Administrator
-entry is for the local administrator, the corinna entry matches the corinna
-account in the domain BAR. The information given in the pw_gecos field
-are all we need to exactly identify an account, and to have a two way
-translation, from Windows account name/SID to Cygwin account name uid and
-vice versa. Having this complete information allows us to choose a Cygwin
-user name and uid which doesn't have to match the Windows account at all. As
-long as the pw_gecos information is available, we're on the safe side:</para>
-
-<example id="ntsec-passwd-tweaked">
-<title>/etc/passwd, tweaked:</title>
-<screen>
-root:unused:0:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
-thursday_next:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
-</screen>
-</example>
-
-<para> The above <filename>/etc/passwd</filename> will still work fine.
-You can now login via <command>ssh</command> as the user "root", and
-Cygwin dutifully translates "root" into the Windows user
-"FOO\Administrator" and files owned by FOO\Administrator are shown to
-have the uid 0 when calling <command>ls -ln</command>. All you do you're
-actually doing as Administrator. Files created as root will be owned by
-FOO\Administrator. And the domain user BAR\corinna can now happily
-pretend to be Thursday Next, but will wake up sooner or later finding
-out she's still actually the domain user BAR\corinna...</para>
-
-<para>Do I have to mention that you can also rename groups in
-<filename>/etc/group</filename>? As long as the SID is present and correct,
-all is well. This allows you to, for instance, rename the "Administrators"
-group to "root" as well:</para>
-
-<example id="ntsec-group-tweaked">
-<title>/etc/group, tweaked:</title>
-<screen>
-root:S-1-5-32-544:544:
-</screen>
-</example>
-
-<para>Last but not least, you can also change the primary group of a user
-in <filename>/etc/passwd</filename>. The only requirement is that the user
-is actually a member of the new primary group in Windows. For instance,
-normal users in a domain environment are members in the group "Domain Users",
-which in turn belongs to the well-known group "Users". So, if it's
-more convenient in your environment for the user's primary group to be
-"Users", just set the user's primary group in <filename>/etc/passwd</filename>
-to the Cygwin uid of "Users" (see in <filename>/etc/group</filename>,
-default 545) and let the user create files with a default group ownership
-of "Users".</para>
+<sect3 id="ntsec-mapping-nfs"><title id="ntsec-mapping-nfs.title">NFS account mapping</title>
-<note><para>
-If you wish to make these kind of changes to /etc/passwd and /etc/group,
-do so only if you feel comfortable with the concepts. Otherwise, do not
-be surprised if things break in either subtle or surprising ways! If you
-do screw things up, revert to copies of <filename>/etc/passwd</filename>
-and <filename>/etc/group</filename> files created by
-<command>mkpasswd</command> and <command>mkgroup</command>. (Make
-backup copies of these files before modifying them.) Especially, don't
-change the UID or the name of the user SYSTEM. It may mostly work, but
-some Cygwin applications running as a local service under that account
-could suddenly start behaving strangely.
-</para></note>
+<para>
+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 applications can
+fetch <ulink url="https://tools.ietf.org/html/rfc1813">RFC 1813</ulink>
+compatible NFSv3 stat information from the share. This is what Cygwin is
+using to show stat information for files on NFS shares.
+</para>
-</sect2>
+<para>
+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.
+</para>
+
+<para>
+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
+<ulink url="http://blogs.technet.com/b/filecab/archive/2012/10/09/nfs-identity-mapping-in-windows-server-2012.aspx">NFS Identity Mapping in Windows Server 2012</ulink>
+</para>
+
+<para>
+Cygwin now utilizes the
+<ulink url="https://tools.ietf.org/html/rfc2307">RFC 2307</ulink>
+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
+<ulink url="https://tools.ietf.org/html/rfc2307">RFC 2307</ulink>, the uid is
+in the attribute <literal>uidNumber</literal>. For groups, the gid is in the
+<literal>gidNumber</literal> attribute.
+</para>
+
+<para>
+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.
+</para>
-<sect2 id="ntsec-ids"><title id="ntsec-ids.title">Special values of user and group ids</title>
-
-<para>If the current user is not present in
-<filename>/etc/passwd</filename>, that user's uid is set to a
-special value of 400. The user name for the current user will always be
-shown correctly. If another user (or a Windows group, treated as a
-user) is not present in <filename>/etc/passwd</filename>, the uid of
-that user will have a special value of -1 (which would be shown by
-<command>ls</command> as 65535). The user name shown in this case will
-be '????????'.</para>
-
-<para>If the current user is not present in
-<filename>/etc/passwd</filename>, that user's login gid is set to a
-special value of 401. The gid 401 is shown as 'mkpasswd',
-indicating the command that should be run to alleviate the
-situation.</para>
-
-<para>If another user is not present in
-<filename>/etc/passwd</filename>, that user's login gid is set to a
-special value of -1. If the user is present in
-<filename>/etc/passwd</filename>, but that user's group is not in
-<filename>/etc/group</filename> and is not the login group of that user,
-the gid is set to a special value of -1. The name of this group
-(id -1) will be shown as '????????'.</para>
-
-<para>If the current user is present in
-<filename>/etc/passwd</filename>, but that user's login group is not
-present in <filename>/etc/group</filename>, the group name will be shown
-as 'mkgroup', again indicating the appropriate command.</para>
-
-<para>A special case is if the current user's primary group SID is noted
-in the user's <filename>/etc/passwd</filename> entry using another group
-id than the group entry of the same group SID in
-<filename>/etc/group</filename>. This should be noted and corrected.
-The group name printed in this case is
-'passwd/group_GID_clash(PPP/GGG)', with PPP being the gid as noted
-in <filename>/etc/passwd</filename> and GGG the gid as noted in
-<filename>/etc/group</filename>.</para>
-
-<para>To summarize:</para>
<itemizedlist spacing="compact">
-<listitem><para>If the current user doesn't show up in
-<filename>/etc/passwd</filename>, it's <emphasis>group</emphasis> will
-be named 'mkpasswd'.</para></listitem>
+<listitem>
+If the server is an AD domain controller, it asks for an account with
+<literal>uidNumber</literal> attribute == <literal>st_uid</literal> 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 <literal>uidNumber</literal> attribute. For
+groups, the method is the same, just that Cygwin asks for a group with
+<literal>gidNumbe</literal> attribute == <literal>st_gid</literal> field of the
+stat record.
+</listitem>
-<listitem><para>Otherwise, if the login group of the current user isn't
-in <filename>/etc/group</filename>, it will be named 'mkgroup'.</para>
+<listitem>
+If the server is a standalone LDAP mapping server Cygwin asks for the
+same <literal>uidNumber</literal>/<literal>gidNumber</literal> 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.
</listitem>
-<listitem><para>Otherwise a group not in <filename>/etc/group</filename>
-will be shown as '????????' and a user not in
-<filename>/etc/passwd</filename> will be shown as "????????".</para>
+</itemizedlist>
+
+<para>
+The mapping will be cached for the lifetime of the process, and inherited
+by child processes.
+</para>
+
+</sect3>
+
+<sect3 id="ntsec-mapping-samba"><title id="ntsec-mapping-samba.title">Samba account mapping</title>
+
+<para>
+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.
+</para>
+
+<para>
+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:
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+A UNIX user account with uid X is mapped to the Windows SID S-1-22-1-X.
</listitem>
-<listitem><para>If different group ids are used for a group with the same
-SID, the group name is shown as 'passwd/group_GID_clash(PPP/GGG)' with
-PPP and GGG being the different group ids.</para></listitem>
+<listitem>
+A UNIX group account with gid X is mapped to SID S-1-22-2-X.
+</listitem>
</itemizedlist>
<para>
-Note that, since the special user and group names are just indicators,
-nothing prevents you from actually having a user named `mkpasswd' in
-<filename>/etc/passwd</filename> (or a group named `mkgroup' in
-<filename>/etc/group</filename>). If you do that, however, be aware of
-the possible confusion.
+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?
+</para>
+
+<para>
+That's what Cygwin will do. If it encounters a S-1-22-x-y SID, it
+will perform the same
+<ulink url="https://tools.ietf.org/html/rfc2307">RFC 2307</ulink>
+mapping as for NFS shares.
+</para>
+
+<para>
+For home users without any Windows domain or LDAP server per
+<ulink url="https://tools.ietf.org/html/rfc2307">RFC 2307</ulink>,
+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.
+</para>
+
+<para>
+To your user's SAM comment (remember: called <literal>Description</literal>
+in the GUI),
+add:
+</para>
+
+<screen>
+ <cygwin group="Users" unix="505"/>
+</screen>
+
+<para>
+To the user's group SAM comment add:
+</para>
+
+<screen>
+ <cygwin unix="100"/>
+</screen>
+
+<para>
+This should be sufficient to work on your Samba share and to see
+all files owned by your Linux user account as your files.
+</para>
+
+</sect3>
+
+<sect3 id="ntsec-mapping-nsswitch"><title id="ntsec-mapping-nsswitch.title">The <filename>/etc/nsswitch.conf</filename> file</title>
+
+<para>
+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
+<ulink url="http://linux.die.net/man/5/nsswitch.conf">/etc/nsswitch.conf</ulink>.
+One part of it is to specify how the passwd and group entries are generated.
+That's what Cygwin now provides as well.
+</para>
+
+<para>
+The <filename>/etc/nsswitch.conf</filename> file is optional. If you don't
+have one, Cygwin uses sensible defaults.
+</para>
+
+<note>
+<para>
+The <filename>/etc/nsswitch.conf</filename> file is read exactly once by
+the first process of a Cygwin process tree. If there was no
+<filename>/etc/nsswitch.conf</filename> file when this first process started,
+then no other process in the running Cygwin process tree will try to read the
+file.
+</para>
+
+<para>
+If you create or change <filename>/etc/nsswitch.conf</filename>, you have to
+restart all Cygwin processes that need to see the change. If the process
+you want to see the change is a child of another process, you need to restart
+all of that process's parents, too.
+</para>
+
+<para>
+For example, if you run <command>vim</command> inside the default Cygwin
+Terminal, <command>vim</command> is a child of your shell, which is a child
+of <command>mintty</command>. If you edit
+<filename>/etc/nsswitch.conf</filename> in that <command>vim</command>
+instance, your shell won't immediately see the change, nor will
+<command>vim</command> if you restart it from that same shell instance.
+This is because both are getting their nsswitch information from their
+ancestor, <command>mintty</command>. You have to start a fresh terminal
+window for the change to take effect.
+</para>
+
+<para>
+By contrast, if you leave that Cygwin Terminal window open after making the
+change to <filename>/etc/nsswitch.conf</filename>, then restart a Cygwin
+service like <command>cron</command>, <command>cron</command> will see the
+change, because it is not a child of <command>mintty</command> or any other
+Cygwin process. (Technically, it is a child of <command>cygrunsrv</command>,
+but that instance also restarts when you restart the service.)
+</para>
+
+<para>
+The reason we point all this out is that the requirements for restarting
+things are not quite as stringent as when you replace
+<filename>cygwin1.dll</filename>. If you have three process trees, you have
+three independent copies of the nsswitch information. If you start a fresh
+process tree, it will see the changes. As long as any process in an existing
+process tree remains running, all processes in that tree will continue to use
+the old information.
+</para>
+</note>
+
+<para>
+So, what settings can we perform with <filename>/etc/nsswitch.conf</filename>?
+To explain, lets have a look into an <filename>/etc/nsswitch.conf</filename>
+file set up to all default values:
+</para>
+
+<screen>
+ # /etc/nsswitch.conf
+ passwd: files db
+ group: files db
+
+ db_prefix: auto
+ db_separator: +
+ db_enum: cache builtin
+</screen>
+
+<para>
+The first line, starting with a hash <literal>#</literal> is a comment.
+The hash character starts a comment, just as in shell scripts. Everything
+up to the end of the line is ignored. So this:
+</para>
+
+<screen>
+ foo: bar # baz
+</screen>
+
+<para>
+means, set "foo" to value "bar", ignore everything after the hash.
+</para>
+
+<para>
+The other lines define the available settings. The first word up to a
+colon is a keyword. Note that the colon <emphasis>must</emphasis> follow
+immediately after the keyword. This is a valid line:
+</para>
+
+<screen>
+ foo: bar
+</screen>
+
+<para>
+This is not valid:
+</para>
+
+<screen>
+ foo : bar
+</screen>
+
+<para>
+Apart from this restriction, the reminder of the line can have as
+many spaces and TABs as you like.
+</para>
+
+<para>
+Now let's have a look at the available keywords and settings.
+</para>
+
+<para>
+The two lines starting with the keywords <literal>passwd:</literal> and
+<literal>group:</literal> define where Cygwin gets its passwd and group
+information from. <literal>files</literal> means, fetch the information
+from the corresponding file in the /etc directory. <literal>db</literal>
+means, fetch the information from the Windows account databases, the SAM
+for local accounts, Active Directory for domain account. Examples:
+</para>
+
+<screen>
+ passwd: files
+</screen>
+
+<para>
+Read passwd entries only from /etc/passwd.
</para>
+<screen>
+ group: db
+</screen>
+
+<para>
+Read group entries only from SAM/AD.
+</para>
+
+<screen>
+ group: files # db
+</screen>
+
+<para>
+Read group entries only from <filename>/etc/group</filename>
+(<literal>db</literal> is only a comment).
+</para>
+
+<screen>
+ passwd: files db
+</screen>
+
+<para>
+Read passwd entries from <filename>/etc/passwd</filename>. If a user account
+isn't found, try to find it in SAM or AD. This is the default for both,
+passwd and group information.
+</para>
+
+<screen>
+ group: db files
+</screen>
+
+<para>
+This is a valid entry, but the order will be ignored by Cygwin. If both,
+<literal>files</literal> and <literal>db</literal> are specified, Cygwin will
+always try the files first, then the db.
+</para>
+
+<para>
+The remaining entries define certain aspects of the Windows account
+database search.
+</para>
+
+<itemizedlist spacing="compact">
+
+<listitem>
+<para>
+<literal>db_prefix:</literal> determines how the Cygwin user or group name
+is created. The recognized values are:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>auto</literal></term>
+ <listitem>
+ <para>
+ This is the default. If your account is from the primary domain of your
+ machine, or if your machine is a standalone machine (not a domain member),
+ your Cygwin account name is just the Windows account name.
+ </para>
+
+ <para>
+ If your account is from another domain, or if you're logged in as
+ local user on a domain machine, the Cygwin username will be the
+ combination of Windows domainname and username, with the separator
+ char in between:
+ </para>
+
+ <segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>MY_DOM+username</literal></seg>
+ <seg>(foreign domain)</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>MACHINE+username</literal></seg>
+ <seg>(local account)</seg>
+ </seglistitem>
+ </segmentedlist>
+
+ <para>
+ Builtin accounts have just the separator char prepended:
+ </para>
+
+ <segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>+LOCAL</literal></seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>+Users</literal></seg>
+ </seglistitem>
+ </segmentedlist>
+
+ <para>
+ Unknown accounts on NFS or Samba shares (that is, accounts which cannot be
+ mapped to Windows user accounts via
+ <ulink url="https://tools.ietf.org/html/rfc2307">RFC 2307</ulink>) get a
+ Cygwin account name consisting of the artificial domains
+ <literal>Unix_User</literal> or <literal>Unix_Group</literal> and the
+ uid/gid value, for instance:
+ </para>
+
+ <segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>Unix_User+0</literal></seg>
+ <seg>(root)</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><literal>Unix_Group+10</literal></seg>
+ <seg>(wheel)</seg>
+ </seglistitem>
+ </segmentedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>primary</literal></term>
+ <listitem>
+ <para>
+ Like <literal>auto</literal>, but primary domain accounts will be
+ prepended by the domainname as well.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>always</literal></term>
+ <listitem>
+ <para>
+ All accounts, even the builtin accounts, will have the domain name
+ prepended:
+ </para>
+
+ <segmentedlist><?dbhtml list-presentation="table"?>
+ <seglistitem>
+ <seg><literal>BUILTIN+Users</literal></seg>
+ </seglistitem>
+ </segmentedlist>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</listitem>
+
+<listitem>
+<para>
+<literal>db_separator:</literal> defines the spearator char used to prepend the
+domain name to the user or group name. The default is the plus character
+<literal>+</literal>.
+</para>
+
+<screen>
+ MY_DOM+username
+</screen>
+
+<para>
+With <literal>db_separator:</literal>, you can define any ASCII char except
+space, tab, carriage return, line feed, and the colon, as separator char.
+Example:
+</para>
+
+<screen>
+ db_separator: \
+</screen>
+
+<para>
+This results in usernames with the backslash as separator:
+</para>
+
+<screen>
+ MY_DOM\username
+</screen>
+
+</listitem>
+
+<listitem>
+<para>
+<literal>db_enum:</literal> defines the depth of a database search, if an
+application calls one of the enumeration functions
+<ulink url="http://linux.die.net/man/3/getpwent">getpwent</ulink>
+or <ulink url="http://linux.die.net/man/3/getgrent">getgrent</ulink>.
+The problem with these functions is, they neither allow to define how many
+entries will be enumerated when calling them in a loop, nor do they
+allow to add some filter criteria. They were designed back in the days,
+when only <filename>/etc/passwd</filename> and <filename>/etc/group</filename>
+files existed and the number of user accounts on a typical UNIX system was
+seldomly a three-digit number.
+</para>
+
+<para>
+These days, with user and group databases sometimes going in the
+six-digit range, they are a potential burden. For that reason, Cygwin
+does not enumerate all user or group accounts by default, but rather
+just a very small list, consisting only of the accounts cached in memory
+by the current process, as well as a handful of predefined builtin
+accounts.
+</para>
+
+<para>
+<literal>db_enum:</literal> allows to specify the accounts to enumerate in a
+fine-grained manner. It takes a list of sources as argument:
+</para>
+
+<screen>
+ db_enum: source1 source2 ...
+</screen>
+
+<para>
+The recognized sources are the following:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>none</literal></term>
+ <listitem>No output from
+ <function>getpwent</function>/<function>getgrent</function>
+ at all.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>all</literal></term>
+ <listitem>The opposite. Enumerates accounts from all known sources, including
+ all trusted domains.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cache</literal></term>
+ <listitem>Enumerate all accounts currently cached in memory.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>builtin</literal></term>
+ <listitem>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).</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>files</literal></term>
+ <listitem>Enumerate the accounts from <filename>/etc/passwd</filename> or
+ <filename>/etc/group</filename>.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>local</literal></term>
+ <listitem>Enumerate all accounts from the local SAM.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>primary</literal></term>
+ <listitem>Enumerate all accounts from the primary domain.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>alltrusted</literal></term>
+ <listitem>Enumerate all accounts from all trusted domains.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>some.domain</literal></term>
+ <listitem>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.</listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Please note that <function>getpwent</function>/<function>getgrent</function>
+do <emphasis>not</emphasis> test if an account was already listed from another
+source, so an account can easily show up twice or three times. Such a test
+would be rather tricky, nor does the Linux implementation perform such test.
+Here are a few examples for <filename>/etc/nsswitch.conf</filename>:
+</para>
+
+<screen>
+ db_enum: none
+</screen>
+
+<para>
+No output from <function>getpwent</function>/<function>getgrent</function>
+at all. The first call to the function immediately returns a NULL pointer.
+</para>
+
+<screen>
+ db_enum: cache files
+</screen>
+
+<para>
+Enumerate all accounts cached by the current process, plus all entries
+from either the /etc/passwd or /etc/group file.
+</para>
+
+<screen>
+ db_enum: cache local primary
+</screen>
+
+<para>
+Enumerate all accounts cached by the current process, all accounts from the SAM
+of the local machine, and all accounts from the primary domain of the machine.
+</para>
+
+<screen>
+ db_enum: local primary alltrusted
+</screen>
+
+<para>
+Enumerate the accounts from the machine's SAM, from the primary domain of the
+machine, and from all trusted domains.
+</para>
+
+<screen>
+ db_enum: primary domain1.corp sub.domain.corp domain2.net
+</screen>
+
+<para>
+Enumerate the accounts from the primary domain and from the domains
+domain1.corp, sub.domain.corp and domain2.net.
+</para>
+
+<screen>
+ db_enum: all
+</screen>
+
+<para>
+Enumerate everything and the kitchen sink.
+</para>
+
+</listitem>
+
+</itemizedlist>
+
+</sect3>
+
+
</sect2>
+<sect2 id="ntsec-files"><title id="ntsec-files.title">File permissions</title>
-<sect2 id="ntsec-mapping"><title id="ntsec-mapping.title">The POSIX permission mapping leak</title>
+<para>On NTFS and if the <literal>noacl</literal> mount option is not
+specified for a mount point, Cygwin sets file permissions as on POSIX
+systems. Basically this is done by defining a Security Descriptor with the
+matching owner and group SIDs, and a DACL which contains ACEs for the owner,
+the group and for "Everyone", which represents what POSIX calls "others".</para>
-<para>As promised earlier, here's the problem when trying to map the
-POSIX permission model onto the Windows permission model.</para>
+<para>There's just one problem when trying to map the POSIX permission model
+onto the Windows permission model.</para>
-<para>There's a leak in the definition of a "correct" ACL which
-disallows a certain POSIX permission setting. The official
-documentation explains in short the following:</para>
+<para>There's a leak in the definition of a "correct" ACL which disallows a
+certain POSIX permission setting. The official documentation explains in short
+the following:</para>
<itemizedlist spacing="compact">
<listitem><para>The requested permissions are checked against all
</screen>
<para>Again: This works on all existing versions of Windows NT, at the
-time of writing from at least Windows XP up to Server 2012. Only
+time of writing from at least Windows XP up to Server 2012 R2. Only
the GUIs aren't able (or willing) to deal with that order.</para>
</sect2>
get its own access token, which allows, for instance, to define threads
with restricted permissions.</para>
-</sect2>
-
-<sect2 id="ntsec-logonuser"><title id="ntsec-logonuser.title">Switching the user context with password authentication</title>
+<sect3 id="ntsec-logonuser"><title id="ntsec-logonuser.title">Switching the user context with password authentication</title>
<para>To switch the user context, the process has to request such an access
token for the new user. This is typically done by calling the Win32 API
</screen>
-</sect2>
+</sect3>
-<sect2 id="ntsec-nopasswd1"><title id="ntsec-nopasswd1.title">Switching the user context without password, Method 1: Create a token from scratch</title>
+<sect3 id="ntsec-nopasswd1"><title id="ntsec-nopasswd1.title">Switching the user context without password, Method 1: Create a token from scratch</title>
<para>An unfortunate aspect of the implementation of
<command>set(e)uid</command> is the fact that the calling process
bash$ grep foo //server/share/foofile
</screen>
-</sect2>
+</sect3>
-<sect2 id="ntsec-nopasswd2"><title id="ntsec-nopasswd2.title">Switching the user context without password, Method 2: LSA authentication package</title>
+<sect3 id="ntsec-nopasswd2"><title id="ntsec-nopasswd2.title">Switching the user context without password, Method 2: LSA authentication package</title>
<para>We're looking for another way to switch the user context without
having to provide the password. Another technique is to create an
<para>Nevertheless, this is already a lot better than what we get by
using <command>NtCreateToken</command>, isn't it?</para>
-</sect2>
+</sect3>
-<sect2 id="ntsec-nopasswd3"><title id="ntsec-nopasswd3.title">Switching the user context without password, Method 3: With password</title>
+<sect3 id="ntsec-nopasswd3"><title id="ntsec-nopasswd3.title">Switching the user context without password, Method 3: With password</title>
<para>Ok, so we have solved almost any problem, except for the network
access problem. Not being able to access network shares without
<para>In all other cases, don't use this method. You have been warned.</para>
-</sect2>
+</sect3>
-<sect2 id="ntsec-setuid-impl"><title id="ntsec-setuid-impl.title">Switching the user context, how does it all fit together?</title>
+<sect3 id="ntsec-setuid-impl"><title id="ntsec-setuid-impl.title">Switching the user context, how does it all fit together?</title>
<para>Now we learned about four different ways to switch the user
context using the <command>set(e)uid</command> system call, but
</listitem>
</itemizedlist>
+</sect3>
+
</sect2>
</sect1>
git://sourceware.org / newlib-cygwin.git / commitdiff