utils.sgml patch for mkgroup, mkpasswd, mount
Joshua Daniel Franklin
joshuadfranklin@yahoo.com
Mon Jul 8 19:39:00 GMT 2002
Here is a patch for utils.sgml that brings mkgroup, mkpasswd, and
mount up to date. All options are now covered with short
explanations of what they are used for, and users are no longer
invited to "mount the directory C:\cygnus\cygwin-b20\H-i586-cygwin32\bin
to /bin". In fact, this patch will get rid of all references to
"C:\cygnus".
I've appropriated words right off the mailing lists so I'd especially
like to thank:
Chris Faylor (Thanks!)
Kazuhiro Fujieda (Arigatou!)
Corinna Vinschen (Danke!)
for their information.
P.S. This also fixes a SNAFU with the spacing for kill's usage output.
-------------- next part --------------
--- utils.sgml-orig 2002-07-08 21:27:06.000000000 -0500
+++ utils.sgml 2002-07-08 21:26:05.000000000 -0500
@@ -268,12 +268,12 @@ The format for ACL output is as follows:
<screen>
Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
-kill -l [signal]
--f, --force force, using win32 interface if necessary
--l, --list print a list of signal names
--s, --signal send signal (use kill --list for a list)
--h, --help output usage information and exit
--v, --version output version information and exit
+ kill -l [signal]
+ -f, --force force, using win32 interface if necessary
+ -l, --list print a list of signal names
+ -s, --signal send signal (use kill --list for a list)
+ -h, --help output usage information and exit
+ -v, --version output version information and exit
</screen>
<para>The <command>kill</command> program allows you to send arbitrary
@@ -388,9 +388,11 @@ One of `-l' or `-d' must be given on NT/
<para>The <command>mkgroup</command> program can be used to help
configure your Windows system to be more UNIX-like by creating an
initial <filename>/etc/group</filename> substitute (some commands need this
-file) from your system information. It only works on NT.
-To initially set up your machine,
-you'd do something like this:</para>
+file) from your system information. It only works on the NT series
+(Windows NT, 2000, and XP). <command>mkgroup</command> does not work on
+the Win9x series (Windows 95, 98, and Me) because they lack the security model
+to support it. To initially set up your machine, you'd do something like
+this:</para>
<example><title>Setting up the groups file</title>
<screen>
@@ -405,7 +407,16 @@ for it to have the new information.</par
<para>The <literal>-d</literal> and <literal>-l</literal> options
allow you to specify where the information comes from, either the
-local machine or the default (or given) domain.</para>
+local machine or the default (or given) domain. The <literal>-o</literal>
+option allows for special cases (such as multiple domains) where the GIDs
+might match otherwise. The <literal>-s</literal>
+option omits the NT Security Identifier (SID). For more information on
+SIDs, see <Xref Linkend="ntsec"> in the Cygwin User's Guide. The
+<literal>-u</literal> option causes <command>mkgroup</command> to
+enumerate the users for each group, placing the group members in the
+gr_mem (last) field. Note that this can greatly increase
+the time for <command>mkgroup</command> to run in a large domain.
+</para>
</sect2>
@@ -438,8 +449,11 @@ One of `-l', `-d' or `-g' must be given
<para>The <command>mkpasswd</command> program can be used to help
configure your Windows system to be more UNIX-like by creating an
initial <filename>/etc/passwd</filename> substitute (some commands
-need this file) from your system information. It only works on NT.
-To initially set up your machine, you'd do something like this:</para>
+need this file) from your system information. It only works on the NT series
+(Windows NT, 2000, and XP). <command>mkpasswd</command> does not work on
+the Win9x series (Windows 95, 98, and Me) because they lack the security model
+to support it. To initially set up your machine, you'd do something like
+this:</para>
<example><title>Setting up the passwd file</title>
<screen>
@@ -454,84 +468,28 @@ for it to have the new information.</par
<para>The <literal>-d</literal> and <literal>-l</literal> options
allow you to specify where the information comes from, either the
-local machine or the default (or given) domain.</para>
-
-</sect2>
-
-<sect2 id="passwd"><title>passwd</title>
+local machine or the default (or given) domain. The <literal>-o</literal>
+option allows for special cases (such as multiple domains) where the UIDs
+might match otherwise. The <literal>-g</literal> option creates a local
+user that corresponds to each local group. This is because NT assigns groups
+file ownership. The <literal>-m</literal> option bypasses the current
+mount table so that, for example, two users who have a Windows home
+directory of H: could mount them differently. The <literal>-s</literal>
+option omits the NT Security Identifier (SID). For more information on
+SIDs, see <Xref Linkend="ntsec"> in the Cygwin User's Guide. The
+<literal>-p</literal> option causes <command>mkpasswd</command> to
+use a prefix other than <literal>/home/</literal>. For example, this command:
+<example><title>Using an alternate home root</title>
<screen>
-Usage: passwd (-l|-u|-S) [USER]
- passwd [-i NUM] [-n MINDAYS] [-x MAXDAYS] [-L LEN]
-
-User operations:
- -l, --lock lock USER's account
- -u, --unlock unlock USER's account
- -S, --status display password status for USER (locked, expired, etc.)
-
-System operations:
- -i, --inactive set NUM of days before inactive accounts are disabled
- (inactive accounts are those with expired passwords)
- -n, --minage set system minimum password age to MINDAYS
- -x, --maxage set system maximum password age to MAXDAYS
- -L, --length set system minimum password length to LEN
-
-Other options:
- -h, --help output usage information and exit
- -v, --version output version information and exit
+<prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" > /etc/passwd</userinput>
</screen>
+</example>
-<para> <command>passwd</command> changes passwords for user accounts.
-A normal user may only change the password for their own account,
-the administrators may change the password for any account.
-<command>passwd</command> also changes account information, such as
-password expiry dates and intervals.</para>
-
-<para>Password changes: The user is first prompted for their old
-password, if one is present. This password is then encrypted and
-compared against the stored password. The user has only one chance to
-enter the correct password. The administrators are permitted to
-bypass this step so that forgotten passwords may be changed.</para>
-
-<para>The user is then prompted for a replacement password.
-<command>passwd</command> will prompt again and compare the second entry
-against the first. Both entries are require to match in order for the
-password to be changed.</para>
-
-<para>After the password has been entered, password aging information
-is checked to see if the user is permitted to change their password
-at this time. If not, <command>passwd</command> refuses to change the
-password and exits.</para>
-
-<para>Password expiry and length: The password aging information may be
-changed by the administrators with the <literal>-x</literal>,
-<literal>-n</literal> and <literal>-i</literal> options. The
-<literal>-x</literal> option is used to set the maximum number of days
-a password remains valid. After <emphasis>max</emphasis> days, the
-password is required to be changed. The <literal>-n</literal> option is
-used to set the minimum number of days before a password may be changed.
-The user will not be permitted to change the password until
-<emphasis>min</emphasis> days have elapsed. The <literal>-i</literal>
-option is used to disable an account after the password has been expired
-for a number of days. After a user account has had an expired password
-for <emphasis>inact</emphasis> days, the user may no longer sign on to
-the account. Allowed values for the above options are 0 to 999. The
-<literal>-L</literal> option sets the minimum length of allowed passwords
-for users, which doesn't belong to the administrators group, to
-<emphasis>len</emphasis> characters. Allowed values for the minimum
-password length are 0 to 14. In any of the above cases, a value of 0
-means `no restrictions'.</para>
-
-<para>Account maintenance: User accounts may be locked and unlocked with the
-<literal>-l</literal> and <literal>-u</literal> flags. The
-<literal>-l</literal> option disables an account. The <literal>-u</literal>
-option re-enables an account.</para>
-
-<para>The account status may be given with the <literal>-S</literal>
-option. The status information is self explanatory.</para>
-
-<para>Limitations: Users may not be able to change their password on
-some systems.</para>
+would put local users' home directories in the Windows 'Profiles' directory.
+The <literal>-u</literal> option allows <command>mkpasswd</command> to
+search for a specific username, greatly reducing the amount of time it
+takes in a large domain.
</sect2>
@@ -574,15 +532,16 @@ will display the current mount table for
<example>
<title>Displaying the current set of mount points</title>
<screen>
-<prompt>c:\cygnus\></prompt> <userinput>mount</userinput>
-Device Directory Type Flags
-D: /d user textmode
-C: / system textmode
+<prompt>c:\cygwin\></prompt> <userinput>mount</userinput>
+c:\cygwin\bin on /usr/bin type system (binmode)
+c:\cygwin\lib on /usr/lib type system (binmode)
+c:\cygwin on / type system (binmode)
+c: on /c type user (binmode,noumount)
+d: on /d type user (binmode,noumount)
</screen>
</example>
-<para>In this example, the C
-drive is the POSIX root and D drive is mapped to
+<para>In this example, c:\cygwin is the POSIX root and D drive is mapped to
<filename>/d</filename>. Note that in this case, the root mount is a
system-wide mount point that is visible to all users running Cygwin
programs, whereas the <filename>/d</filename> mount is only visible
@@ -591,31 +550,23 @@ to the current user.</para>
<para>The <command>mount</command> utility is also the mechanism for
adding new mounts to the mount table. The following example
demonstrates how to mount the directory
-<filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</filename>
-to <filename>/bin</filename> and the network directory
<filename>\\pollux\home\joe\data</filename> to <filename>/data</filename>.
-<filename>/bin</filename> is assumed to already exist.</para>
+</para>
<example>
<title>Adding mount points</title>
<screen>
-<prompt>c:\cygnus\></prompt> <userinput>ls /bin /data</userinput>
+<prompt>c:\cygwin\></prompt> <userinput>ls /data</userinput>
ls: /data: No such file or directory
-<prompt>c:\cygnus\></prompt> <userinput>mount C:\cygnus\cygwin-b20\H-i586-cygwin32\bin /bin</userinput>
-<prompt>c:\cygnus\></prompt> <userinput>mount \\pollux\home\joe\data /data</userinput>
-Warning: /data does not exist!
-<prompt>c:\cygnus\></prompt> <userinput>mount</userinput>
-Device Directory Type Flags
-\\pollux\home\joe\data /data user textmode
-C:\cygnus\cygwin-b20\H-i586-cygwin32\bin /bin user textmode
-D: /d user textmode
-\\.\tape1: /dev/st1 user textmode
-\\.\tape0: /dev/st0 user textmode
-\\.\b: /dev/fd1 user textmode
-\\.\a: /dev/fd0 user textmode
-C: / system textmode
-<prompt>c:\cygnus\></prompt> <userinput>ls /bin/sh</userinput>
-/bin/sh
+<prompt>c:\cygwin\></prompt> <userinput>mount \\pollux\home\joe\data /data</userinput>
+mount: warning - /data does not exist!
+<prompt>c:\cygwin\></prompt> <userinput>mount</userinput>
+\\pollux\home\joe\data on /data type sytem (binmode)
+c:\cygwin\bin on /usr/bin type system (binmode)
+c:\cygwin\lib on /usr/lib type system (binmode)
+c:\cygwin on / type system (binmode)
+c: on /c type user (binmode,noumount)
+d: on /d type user (binmode,noumount)
</screen>
</example>
@@ -624,7 +575,7 @@ command shell in the previous example.
bash, it is legal and convenient to use the forward "/" in Win32
pathnames since the "\" is the shell's escape character. </para>
-<para>The "-s" flag to <command>mount</command> is used to add a mount
+<para>The <literal>-s</literal> flag to <command>mount</command> is used to add a mount
in the system-wide mount table used by all Cygwin users on the system,
instead of the user-specific one. System-wide mounts are displayed
by <command>mount</command> as being of the "system" type, as is the
@@ -634,25 +585,38 @@ permitted to modify the system-wide moun
<para>Note that a given POSIX path may only exist once in the user
table and once in the global, system-wide table. Attempts to replace
-the mount will fail with a busy error. The "-f" (force) flag causes
+the mount will fail with a busy error. The <literal>-f</literal> (force) flag causes
the old mount to be silently replaced with the new one. It will also
silence warnings about the non-existence of directories at the Win32
path location.</para>
-<para>The "-b" flag is used to instruct Cygwin to treat binary and
+<para>The <literal>-b</literal> flag is used to instruct Cygwin to treat binary and
text files in the same manner by default. Binary mode mounts are
marked as "binmode" in the Flags column of <command>mount</command>
output. By default, mounts are in text mode ("textmode" in the Flags
column).</para>
-<para>The "-x" flag is used to instruct Cygwin that the mounted file
-is "executable". If the "-x" flag is used with a directory then
-all files in the directory are executable. Files ending in certain
-extensions (.exe, .com, .bat, .cmd) are assumed to be executable
-by default. Files whose first two characters begin with '#!' are
-also considered to be executable. This option allows other files
-to be marked as executable and avoids the overhead of opening each
-file to check for a '#!'.</para>
+<para>Normally, files ending in certain extensions (.exe, .com, .bat, .cmd)
+are assumed to be executable. Files whose first two characters begin with
+'#!' are also considered to be executable.
+The <literal>-x</literal> flag is used to instruct Cygwin that the
+mounted file is "executable". If the <literal>-x</literal> flag is used
+with a directory then all files in the directory are executable.
+This option allows other files to be marked as executable and avoids the
+overhead of opening each file to check for a '#!'. The <literal>-X</literal>
+option is very similar to <literal>-x</literal>, but also prevents Cygwin
+from setting up commands and environment variables for a normal Windows
+program, adding another small performance gain. The opposite of these
+flags is the <literal>-E</literal> flag, which means that no files should be
+marked as executable. </para>
+
+<para>
+The <literal>-m</literal> option causes the <command>mount</command> utility
+to output a series of commands that could recreate both user and system mount
+points. You can save this output as a backup when experimenting with the
+mount table. It also makes moving your settings to a different machine
+much easier.
+</para>
</sect3>
@@ -662,29 +626,27 @@ file to check for a '#!'.</para>
from a particular Win32 path to a POSIX one, Cygwin will, instead,
convert to a POSIX path using a default mount point:
<filename>/cygdrive</filename>. For example, if Cygwin accesses
-<filename>Z:\foo</filename> and the Z drive is not currently in the
-mount table, then <filename>Z:\</filename> will be accessible as
-<filename>/cygdrive/Z</filename>. The default prefix of
-<filename>/cygdrive</filename> may be changed via the
-<Xref Linkend="mount"> command.</para>
-
-<para>The <command>mount</command> utility can be used to change this
-default automount prefix through the use of the
-"--change-cygdrive-prefix" flag. In the following example, we will
+<filename>z:\foo</filename> and the z drive is not currently in the
+mount table, then <filename>z:\</filename> will be accessible as
+<filename>/cygdrive/z</filename>. The <command>mount</command> utility
+can be used to change this default automount prefix through the use of the
+"--change-cygdrive-prefix" option. In the following example, we will
set the automount prefix to <filename>/</filename>:</para>
<example>
<title>Changing the default prefix</title>
<screen>
-<prompt>c:\cygnus\></prompt> <userinput>mount --change-cygdrive-prefix /</userinput>
+<prompt>c:\cygwin\></prompt> <userinput>mount --change-cygdrive-prefix /</userinput>
</screen>
</example>
<para>Note that you if you set a new prefix in this manner, you can
-specify the "-s" flag to make this the system-wide default prefix. By
-default, the cygdrive-prefix applies only to the current user. In the
-same way, you can specify the "-b" flag such that all new automounted
-filesystems default to binary mode file accesses.</para>
+specify the <literal>-s</literal> flag to make this the system-wide default
+prefix. By default, the cygdrive-prefix applies only to the current user.
+You can always see the user and system cygdrive prefixes with the
+<literal>-p</literal> option. Using the <literal>-b</literal>
+flag with <literal>--change-cygdrive-prefix</literal> makes all new
+automounted filesystems default to binary mode file accesses.</para>
</sect3>
@@ -724,6 +686,83 @@ find <filename>mtpt</filename>.
</sect2>
+<sect2 id="passwd"><title>passwd</title>
+
+<screen>
+Usage: passwd (-l|-u|-S) [USER]
+ passwd [-i NUM] [-n MINDAYS] [-x MAXDAYS] [-L LEN]
+
+User operations:
+ -l, --lock lock USER's account
+ -u, --unlock unlock USER's account
+ -S, --status display password status for USER (locked, expired, etc.)
+
+System operations:
+ -i, --inactive set NUM of days before inactive accounts are disabled
+ (inactive accounts are those with expired passwords)
+ -n, --minage set system minimum password age to MINDAYS
+ -x, --maxage set system maximum password age to MAXDAYS
+ -L, --length set system minimum password length to LEN
+
+Other options:
+ -h, --help output usage information and exit
+ -v, --version output version information and exit
+</screen>
+
+<para> <command>passwd</command> changes passwords for user accounts.
+A normal user may only change the password for their own account,
+the administrators may change the password for any account.
+<command>passwd</command> also changes account information, such as
+password expiry dates and intervals.</para>
+
+<para>Password changes: The user is first prompted for their old
+password, if one is present. This password is then encrypted and
+compared against the stored password. The user has only one chance to
+enter the correct password. The administrators are permitted to
+bypass this step so that forgotten passwords may be changed.</para>
+
+<para>The user is then prompted for a replacement password.
+<command>passwd</command> will prompt again and compare the second entry
+against the first. Both entries are require to match in order for the
+password to be changed.</para>
+
+<para>After the password has been entered, password aging information
+is checked to see if the user is permitted to change their password
+at this time. If not, <command>passwd</command> refuses to change the
+password and exits.</para>
+
+<para>Password expiry and length: The password aging information may be
+changed by the administrators with the <literal>-x</literal>,
+<literal>-n</literal> and <literal>-i</literal> options. The
+<literal>-x</literal> option is used to set the maximum number of days
+a password remains valid. After <emphasis>max</emphasis> days, the
+password is required to be changed. The <literal>-n</literal> option is
+used to set the minimum number of days before a password may be changed.
+The user will not be permitted to change the password until
+<emphasis>min</emphasis> days have elapsed. The <literal>-i</literal>
+option is used to disable an account after the password has been expired
+for a number of days. After a user account has had an expired password
+for <emphasis>inact</emphasis> days, the user may no longer sign on to
+the account. Allowed values for the above options are 0 to 999. The
+<literal>-L</literal> option sets the minimum length of allowed passwords
+for users, which doesn't belong to the administrators group, to
+<emphasis>len</emphasis> characters. Allowed values for the minimum
+password length are 0 to 14. In any of the above cases, a value of 0
+means `no restrictions'.</para>
+
+<para>Account maintenance: User accounts may be locked and unlocked with the
+<literal>-l</literal> and <literal>-u</literal> flags. The
+<literal>-l</literal> option disables an account. The <literal>-u</literal>
+option re-enables an account.</para>
+
+<para>The account status may be given with the <literal>-S</literal>
+option. The status information is self explanatory.</para>
+
+<para>Limitations: Users may not be able to change their password on
+some systems.</para>
+
+</sect2>
+
<sect2 id="ps"><title>ps</title>
<screen>
More information about the Cygwin-patches
mailing list