diff options
| -rw-r--r-- | winsup/utils/utils.sgml | 313 |
1 files changed, 176 insertions, 137 deletions
diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml index 2cbec03bb..badd89be2 100644 --- a/winsup/utils/utils.sgml +++ b/winsup/utils/utils.sgml @@ -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/W2K. <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.</para> <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 on NT/W2K. <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.</para> <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 you.</para> <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. In many Unix shells, including 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 mount table.</para> <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> |