diff --git a/share/skel/dot.profile b/share/skel/dot.profile index 40dfa58f4e84..d67a6e2a934b 100644 --- a/share/skel/dot.profile +++ b/share/skel/dot.profile @@ -1,29 +1,29 @@ # -# .profile - Bourne Shell startup script for login shells +# .profile - POSIX Shell startup script for login shells # # see also sh(1), environ(7). # # These are normally set through /etc/login.conf. You may override them here # if wanted. # PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:$HOME/bin; export PATH # Setting TERM is normally done through /etc/ttys. Do only override # if you're sure that you'll never log in via telnet or xterm or a # serial line. # TERM=xterm; export TERM EDITOR=vi; export EDITOR PAGER=less; export PAGER # set ENV to a file invoked each time sh is started for interactive use. ENV=$HOME/.shrc; export ENV # Let sh(1) know it's at home, despite /home being a symlink. if [ "$PWD" != "$HOME" ] && [ "$PWD" -ef "$HOME" ] ; then cd ; fi # Query terminal size; useful for serial lines. if [ -x /usr/bin/resizewin ] ; then /usr/bin/resizewin -z ; fi # Display a random cookie on each login. if [ -x /usr/bin/fortune ] ; then /usr/bin/fortune freebsd-tips ; fi diff --git a/usr.bin/apply/apply.1 b/usr.bin/apply/apply.1 index f1c114d40814..1e0115364e81 100644 --- a/usr.bin/apply/apply.1 +++ b/usr.bin/apply/apply.1 @@ -1,137 +1,137 @@ .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd January 28, 2022 .Dt APPLY 1 .Os .Sh NAME .Nm apply .Nd apply a command to a set of arguments .Sh SYNOPSIS .Nm .Op Fl a Ar c .Op Fl d .Op Cm - Ns Ar # .Ar command argument ... .Sh DESCRIPTION The .Nm utility runs the named .Ar command on each argument .Ar argument in turn. .Pp Character sequences of the form .Dq Li \&%d in .Ar command , where .Sq Li d is a digit from 1 to 9, are replaced by the .Li d Ns \'th following unused .Ar argument . In this case, the largest digit number of arguments are discarded for each execution of .Ar command . .Pp The options are as follows: .Bl -tag -width indent .It Cm - Ns Ar # Normally arguments are taken singly; the optional number .Ar # specifies the number of arguments to be passed to .Ar command . If the number is zero, .Ar command is run, without arguments, once for each .Ar argument . .Pp If any sequences of .Dq Li \&%d occur in .Ar command , the .Fl # option is ignored. .It Fl a Ar c The use of the character .Sq Li % as a magic character may be changed with the .Fl a option. .It Fl d Display the commands that would have been executed, but do not actually execute them. .El .Sh ENVIRONMENT The following environment variable affects the execution of .Nm : .Bl -tag -width SHELL .It Ev SHELL Pathname of shell to use. -If this variable is not defined, the Bourne shell is used. +If this variable is not defined, the POSIX shell is used. .El .Sh FILES .Bl -tag -width /bin/sh -compact .It Pa /bin/sh default shell .El .Sh EXAMPLES .Bl -tag -width apply -compact .It Li "apply echo *" is similar to .Xr ls 1 ; .It Li "apply \-2 cmp a1 b1 a2 b2 a3 b3" compares the `a' files to the `b' files; .It Li "apply \-0 who 1 2 3 4 5" runs .Xr who 1 5 times; and .It Li "apply \'ln %1 /usr/joe\'" * links all files in the current directory to the directory .Pa /usr/joe . .El .Sh HISTORY The .Nm command appeared in .Bx 4.2 . .Sh AUTHORS .An Rob Pike .Sh BUGS Shell metacharacters in .Ar command may have bizarre effects; it is best to enclose complicated commands in single quotes .Pq '' . .Pp The .Nm utility does not recognize multibyte characters. diff --git a/usr.bin/chpass/chpass.1 b/usr.bin/chpass/chpass.1 index 0891f3f28c92..0321d748a1a4 100644 --- a/usr.bin/chpass/chpass.1 +++ b/usr.bin/chpass/chpass.1 @@ -1,488 +1,488 @@ .\" Copyright (c) 1988, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 25, 2021 .Dt CHPASS 1 .Os .Sh NAME .Nm chpass , .Nm chfn , .Nm chsh , .Nm ypchpass , .Nm ypchfn , .Nm ypchsh .Nd add or change user database information .Sh SYNOPSIS .Nm chpass .Op Fl a Ar list .Op Fl e Ar expiretime .Op Fl p Ar encpass .Op Fl s Ar newshell .Op user .Nm ypchpass .Op Fl loy .Op Fl a Ar list .Op Fl d Ar domain .Op Fl e Ar expiretime .Op Fl h Ar host .Op Fl p Ar encpass .Op Fl s Ar newshell .Op user .Sh DESCRIPTION The .Nm utility allows editing of the user database information associated with .Ar user or, by default, the current user. .Pp The .Nm chfn , .Nm chsh , .Nm ypchpass , .Nm ypchfn and .Nm ypchsh utilities behave identically to .Nm . (There is only one program.) .Pp The information is formatted and supplied to an editor for changes. .Pp Only the information that the user is allowed to change is displayed. .Pp The options are as follows: .Bl -tag -width "-e expiretime" .It Fl a Ar list The super-user is allowed to directly supply a user database entry, in the format specified by .Xr passwd 5 , as an argument. This argument must be a colon .Pq Dq \&: separated list of all the user database fields, although they may be empty. .It Fl e Ar expiretime Change the account expire time. This option is used to set the expire time from a script as if it was done in the interactive editor. .It Fl p Ar encpass The super-user is allowed to directly supply an encrypted password field, in the format used by .Xr crypt 3 , as an argument. .It Fl s Ar newshell Attempt to change the user's shell to .Ar newshell . .El .Pp Possible display items are as follows: .Pp .Bl -tag -width "Other Information:" -compact -offset indent .It Login: user's login name .It Password: user's encrypted password .It Uid: user's login .It Gid: user's login group .It Class: user's general classification .It Change: password change time .It Expire: account expiration time .It Full Name: user's real name .It Office Location: user's office location (1) .It Office Phone: user's office phone (1) .It Home Phone: user's home phone (1) .It Other Information: any locally defined parameters for user (1) .It Home Directory: user's home directory .It Shell: user's login shell .Pp .It NOTE(1) - In the actual master.passwd file, these fields are comma-delimited fields embedded in the FullName field. .El .Pp The .Ar login field is the user name used to access the computer account. .Pp The .Ar password field contains the encrypted form of the user's password. .Pp The .Ar uid field is the number associated with the .Ar login field. Both of these fields should be unique across the system (and often across a group of systems) as they control file access. .Pp While it is possible to have multiple entries with identical login names and/or identical user id's, it is usually a mistake to do so. Routines that manipulate these files will often return only one of the multiple entries, and that one by random selection. .Pp The .Ar gid field is the group that the user will be placed in at login. Since .Bx supports multiple groups (see .Xr groups 1 ) this field currently has little special meaning. This field may be filled in with either a number or a group name (see .Xr group 5 ) . .Pp The .Ar class field references class descriptions in .Pa /etc/login.conf and is typically used to initialize the user's system resource limits when they login. .Pp The .Ar change field is the date by which the password must be changed. .Pp The .Ar expire field is the date on which the account expires. .Pp Both the .Ar change and .Ar expire fields should be entered in the form .Dq month day year where .Ar month is the month name (the first three characters are sufficient), .Ar day is the day of the month, and .Ar year is the year. .Pp Five fields are available for storing the user's .Ar full name , office location , .Ar work and .Ar home telephone numbers and finally .Ar other information which is a single comma delimited string to represent any additional gecos fields (typically used for site specific user information). Note that .Xr finger 1 will display the office location and office phone together under the heading .Ar Office\&: . .Pp The user's .Ar home directory is the full .Ux path name where the user will be placed at login. .Pp The .Ar shell field is the command interpreter the user prefers. If the .Ar shell -field is empty, the Bourne shell, +field is empty, the POSIX shell, .Pa /bin/sh , is assumed. When altering a login shell, and not the super-user, the user may not change from a non-standard shell or to a non-standard shell. Non-standard is defined as a shell not found in .Pa /etc/shells . .Pp Once the information has been verified, .Nm uses .Xr pwd_mkdb 8 to update the user database. .Sh ENVIRONMENT The .Xr vi 1 editor will be used unless the environment variable .Ev EDITOR is set to an alternate editor. When the editor terminates, the information is re-read and used to update the user database itself. Only the user, or the super-user, may edit the information associated with the user. .Pp See .Xr pwd_mkdb 8 for an explanation of the impact of setting the .Ev PW_SCAN_BIG_IDS environment variable. .Sh NIS INTERACTION The .Nm utility can also be used in conjunction with NIS, however some restrictions apply. Currently, .Nm can only make changes to the NIS passwd maps through .Xr rpc.yppasswdd 8 , which normally only permits changes to a user's password, shell and GECOS fields. Except when invoked by the super-user on the NIS master server, .Nm (and, similarly, .Xr passwd 1 ) cannot use the .Xr rpc.yppasswdd 8 server to change other user information or add new records to the NIS passwd maps. Furthermore, .Xr rpc.yppasswdd 8 requires password authentication before it will make any changes. The only user allowed to submit changes without supplying a password is the super-user on the NIS master server; all other users, including those with root privileges on NIS clients (and NIS slave servers) must enter a password. (The super-user on the NIS master is allowed to bypass these restrictions largely for convenience: a user with root access to the NIS master server already has the privileges required to make updates to the NIS maps, but editing the map source files by hand can be cumbersome. .Pp Note: these exceptions only apply when the NIS master server is a .Fx system). .Pp Consequently, except where noted, the following restrictions apply when .Nm is used with NIS: .Bl -enum -offset indent .It .Em "Only the shell and GECOS information may be changed" . All other fields are restricted, even when .Nm is invoked by the super-user. While support for changing other fields could be added, this would lead to compatibility problems with other NIS-capable systems. Even though the super-user may supply data for other fields while editing an entry, the extra information (other than the password \(em see below) will be silently discarded. .Pp Exception: the super-user on the NIS master server is permitted to change any field. .It .Em "Password authentication is required" . The .Nm utility will prompt for the user's NIS password before effecting any changes. If the password is invalid, all changes will be discarded. .Pp Exception: the super-user on the NIS master server is allowed to submit changes without supplying a password. (The super-user may choose to turn off this feature using the .Fl o flag, described below.) .It .Em "Adding new records to the local password database is discouraged" . The .Nm utility will allow the administrator to add new records to the local password database while NIS is enabled, but this can lead to some confusion since the new records are appended to the end of the master password file, usually after the special NIS '+' entries. The administrator should use .Xr vipw 8 to modify the local password file when NIS is running. .Pp The super-user on the NIS master server is permitted to add new records to the NIS password maps, provided the .Xr rpc.yppasswdd 8 server has been started with the .Fl a flag to permitted additions (it refuses them by default). The .Nm utility tries to update the local password database by default; to update the NIS maps instead, invoke chpass with the .Fl y flag. .It .Em "Password changes are not permitted". Users should use .Xr passwd 1 or .Xr yppasswd 1 to change their NIS passwords. The super-user is allowed to specify a new password (even though the .Dq Password: field does not show up in the editor template, the super-user may add it back by hand), but even the super-user must supply the user's original password otherwise .Xr rpc.yppasswdd 8 will refuse to update the NIS maps. .Pp Exception: the super-user on the NIS master server is permitted to change a user's NIS password with .Nm . .El .Pp There are also a few extra option flags that are available when .Nm is compiled with NIS support: .Bl -tag -width "-d domain" .It Fl d Ar domain Specify a particular NIS domain. The .Nm utility uses the system domain name by default, as set by the .Xr domainname 1 utility. The .Fl d option can be used to override a default, or to specify a domain when the system domain name is not set. .It Fl h Ar host Specify the name or address of an NIS server to query. Normally, .Nm will communicate with the NIS master host specified in the .Pa master.passwd or .Pa passwd maps. On hosts that have not been configured as NIS clients, there is no way for the program to determine this information unless the user provides the hostname of a server. Note that the specified hostname need not be that of the NIS master server; the name of any server, master or slave, in a given NIS domain will do. .Pp When using the .Fl d option, the hostname defaults to .Dq localhost . The .Fl h option can be used in conjunction with the .Fl d option, in which case the user-specified hostname will override the default. .It Fl l Force .Nm to modify the local copy of a user's password information in the event that a user exists in both the local and NIS databases. .It Fl o Force the use of RPC-based updates when communicating with .Xr rpc.yppasswdd 8 .Pq Dq old-mode . When invoked by the super-user on the NIS master server, .Nm allows unrestricted changes to the NIS passwd maps using dedicated, non-RPC-based mechanism (in this case, a .Ux domain socket). The .Fl o flag can be used to force .Nm to use the standard update mechanism instead. This option is provided mainly for testing purposes. .It Fl y Opposite effect of .Fl l . This flag is largely redundant since .Nm operates on NIS entries by default if NIS is enabled. .El .Sh FILES .Bl -tag -width /etc/master.passwd -compact .It Pa /etc/master.passwd the user database .It Pa /etc/passwd a Version 7 format password file .It Pa /etc/pw.XXXXXX temporary file .It Pa /etc/shells the list of approved shells .El .Sh EXAMPLES Change the shell of the current user to .Ql /usr/local/bin/zsh : .Bd -literal -offset indent chsh -s /usr/local/bin/zsh .Ed .Sh SEE ALSO .Xr finger 1 , .Xr login 1 , .Xr passwd 1 , .Xr getusershell 3 , .Xr login.conf 5 , .Xr passwd 5 , .Xr pw 8 , .Xr pwd_mkdb 8 , .Xr vipw 8 .Rs .%A Robert Morris .%A Ken Thompson .%T "UNIX Password security" .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.3 Reno . .Sh BUGS User information should (and eventually will) be stored elsewhere. diff --git a/usr.bin/fortune/datfiles/freebsd-tips b/usr.bin/fortune/datfiles/freebsd-tips index 379f772fea88..47fd3c755626 100644 --- a/usr.bin/fortune/datfiles/freebsd-tips +++ b/usr.bin/fortune/datfiles/freebsd-tips @@ -1,870 +1,870 @@ Any user that is a member of the wheel group can use "su -" to simulate a root login. You can add a user to the wheel group with: pw groupmod -n wheel -m user_name -- Konstantinos Konstantinidis % By pressing "Scroll Lock" you can use the arrow keys to scroll backward through the console output. Press "Scroll Lock" again to turn it off. Don't have a "Scroll Lock" key? The "Pause / Break" key acts alike. % Can't remember if you've installed a certain port or not? Try "pkg info -x port_name". % Ever wonder what those numbers after command names were, as in cat(1)? It's the section of the manual the man page is in. "man man" will tell you more. -- David Scheidt % Forget how to spell a word or a variation of a word? Use look portion_of_word_you_know -- Dru % Forget what directory you are in? Type "pwd". -- Dru % Forget when Easter is? Try "ncal -e". If you need the date for Orthodox Easter, use "ncal -o" instead. -- Dru % FreeBSD is started up by the program 'init'. The first thing init does when starting multiuser mode (ie, starting the computer up for normal use) is to run the shell script /etc/rc. By reading /etc/rc and the /etc/rc.d/ scripts, you can learn a lot about how the system is put together, which again will make you more confident about what happens when you do something with it. % Handy bash(1) prompt: PS1="\u@\h \w \!$ " -- David Scheidt % Having trouble using fetch through a firewall? Try setting the environment variable FTP_PASSIVE_MODE to yes, and see fetch(3) for more details. % If other operating systems have damaged your Master Boot Record, you can reinstall it with gpart(8). See "man gpart" for details. % If you accidentally end up inside vi, you can quit it by pressing Escape, colon (:), q (q), bang (!) and pressing return. % If you do not want to get beeps in X11 (X Windows), you can turn them off with xset b off % If you have a CD-ROM drive in your machine, you can make the CD-ROM that is presently inserted available by typing 'mount /cdrom' as root. The CD-ROM will be available under /cdrom/. Remember to do 'umount /cdrom' before removing the CD-ROM (it will usually not be possible to remove the CD-ROM without doing this.) Note: This tip may not work in all configurations. % If you need a reminder to leave your terminal, type "leave +hhmm" where "hhmm" represents in how many hours and minutes you need to leave. -- Dru % If you need to ask a question on the FreeBSD-questions mailing list then https://docs.freebsd.org/en/articles/freebsd-questions contains lots of useful advice to help you get the best results. % If you write part of a filename in tcsh, pressing TAB will show you the available choices when there is more than one, or complete the filename if there's only one match. % If you `set watch = (0 any any)' in tcsh, you will be notified when someone logs in or out of your system. % If you use the C shell, add the following line to the .cshrc file in your home directory to prevent core files from being written to disk: limit coredumpsize 0 -- Dru % If you want df(1) and other commands to display disk sizes in kilobytes instead of 512-byte blocks, set BLOCKSIZE in your environment to 'K'. You can also use 'M' for Megabytes or 'G' for Gigabytes. If you want df(1) to automatically select the best size then use 'df -h'. % If you want to play CDs with FreeBSD, a utility for this is already included. Type 'cdcontrol' then 'help' to learn more. (You may need to set the CDROM environment variable in order to make cdcontrol want to start.) % If you'd like to keep track of applications in the FreeBSD ports tree, take a look at FreshPorts; https://www.freshports.org/ % In order to make fetch (the FreeBSD downloading tool) ask for username/password when it encounters a password-protected web page, you can set the environment variable HTTP_AUTH to 'basic:*'. % In order to search for a string in some files, use 'grep' like this: grep "string" filename1 [filename2 filename3 ...] This will print out the lines in the files that contain the string. grep can also do a lot more advanced searches - type 'man grep' for details. % In order to support national characters for European languages in tools like less without creating other nationalisation aspects, set the environment variable LC_ALL to 'en_US.UTF-8'. % "man firewall" will give advice for building a FreeBSD firewall using ipfw(8). -- David Scheidt % "man hier" will explain the way FreeBSD filesystems are normally laid out. -- David Scheidt % Man pages are divided into section depending on topic. There are 9 different sections numbered from 1 (General Commands) to 9 (Kernel Developer's Manual). You can get an introduction to each topic by typing man intro In other words, to get the intro to general commands, type man 1 intro % "man ports" gives many useful hints about installing FreeBSD ports. % "man security" gives very good advice on how to tune the security of your FreeBSD system. % "man tuning" gives some tips how to tune performance of your FreeBSD system. -- David Scheidt % Need to do a search in a manpage or in a file you've sent to a pager? Use "/search_word". To repeat the same search, type "n" for next or "p" for previous. -- Dru % Need to find the location of a program? Use "locate program_name". -- Dru % Need to leave your terminal for a few minutes and don't want to logout? Use "lock -p". When you return, use your password as the key to unlock the terminal. -- Dru % Need to quickly empty a file? Use ": > filename". -- Dru % Need to quickly return to your home directory? Type "cd". -- Dru % Need to remove all those ^M characters from a DOS file? Try tr -d \\r < dosfile > newfile -- Originally by Dru % Need to see the calendar for this month? Simply type "cal". To see the whole year, type "cal -y". -- Dru % Need to see which daemons are listening for connection requests? Use "sockstat -4l" for IPv4, and "sockstat -l" for IPv4 and IPv6. -- Dru % Need to see your routing table? Type "netstat -rn". The entry with the G flag is your gateway. -- Dru % Nice bash prompt: PS1='(\[$(tput md)\]\t <\w>\[$(tput me)\]) $(echo $?) \$ ' -- Mathieu % Over quota? "du -sh * | sort -h " will give you a sorted list of your directory sizes. -- David Scheidt % nc(1) (or netcat) is useful not only for redirecting input/output to TCP or UDP connections, but also for proxying them with inetd(8). % -sh (the default Bourne shell in FreeBSD) supports command-line editing. Just +sh (the default POSIX shell in FreeBSD) supports command-line editing. Just ``set -o emacs'' or ``set -o vi'' to enable it. Use "" key to complete paths. % Simple tcsh prompt: set prompt = '%# ' % The default editor in FreeBSD is vi, which is efficient to use when you have learned it, but somewhat user-unfriendly. To use ee (an easier but less powerful editor) instead, set the environment variable EDITOR to /usr/bin/ee % Time to change your password? Type "passwd" and follow the prompts. -- Dru % To change an environment variable in /bin/sh use: $ VARIABLE="value" $ export VARIABLE % To change an environment variable in tcsh you use: setenv NAME "value" where NAME is the name of the variable and "value" its new value. % To clear the screen, use "clear". To re-display your screen buffer, press the scroll lock key and use your page up button. When you're finished, press the scroll lock key again to get your prompt back. -- Dru % You can press Ctrl-L while in the shell to clear the screen. % To determine whether a file is a text file, executable, or some other type of file, use file filename -- Dru % To do a fast search for a file, try locate filename locate uses a database that is updated every Saturday (assuming your computer is running FreeBSD at the time) to quickly find files based on name only. % To erase a line you've written at the command prompt, use "Ctrl-U". -- Dru % To find out the hostname associated with an IP address, use drill -x IP_address -- Dru % To obtain a neat PostScript rendering of a manual page, use ``-t'' switch of the man(1) utility: ``man -t ''. For example: man -t grep > grep.ps # Save the PostScript version to a file or man -t printf | lp # Send the PostScript directly to printer % To quickly create an empty file, use "touch filename". -- Dru % To read a compressed file without having to first uncompress it, use "zcat" or "zless" to view it. There is also "bzcat", "bzless", "xzcat" and "xzless". -- Dru % To save disk space in your home directory, compress files you rarely use with "gzip filename". -- Dru % To search for files that match a particular name, use find(1); for example find / -name "*GENERIC*" -ls will search '/', and all subdirectories, for files with 'GENERIC' in the name. -- Stephen Hilton % To see all of the directories on your FreeBSD system, type find / -type d | less All the files? find / -type f | less % To see how long it takes a command to run, type the word "time" before the command name. -- Dru % To see how much disk space is left on your UFS partitions, use df -h -- Dru % To see the 10 largest files in a directory or on a UFS partition, use du -h /partition_or_directory_name | sort -rh | head -- Dru % To see the IP addresses currently set on your active interfaces, type "ifconfig -u". -- Dru % To see the last 10 lines of a long file, use "tail filename". To see the first 10 lines, use "head filename". To see new lines as they're appended to a file, use "tail -f filename". -- Dru % To see the last time that you logged in, use lastlogin(8). -- Dru % To see the MAC addresses of the NICs on your system, type ifconfig -a -- Dru % To see the output from when your computer started, run dmesg(8). If it has been replaced with other messages, look at /var/run/dmesg.boot. -- Francisco Reyes % Want colour in your directory listings? Use "ls -G". "ls -F" is also useful, and they can be combined as "ls -FG". % Want to find a specific port? Just type the following under /usr/ports or one of its subdirectories: make search name= or make search key= % Want to know how many words, lines, or bytes are contained in a file? Type "wc filename". -- Dru % Want to see how much virtual memory you're using? Just type "swapinfo" to be shown information about the usage of your swap partitions. % Want to strip UTF-8 BOM(Byte Order Mark) from given files? sed -e '1s/^\xef\xbb\xbf//' < bomfile > newfile % Want to use sed(1) to edit a file in place? Well, to replace every 'e' with an 'o', in a file named 'foo', you can do: sed -i.bak s/e/o/g foo And you'll get a backup of the original in a file named 'foo.bak', but if you want no backup: sed -i '' s/e/o/g foo % When you've made modifications to a file in vi(1) and then find that you can't write it, type ``!rm -f %'' then ``:w!'' to force the write This won't work if you don't have write permissions to the directory and probably won't be suitable if you're editing through a symbolic link. If you have sudo(8) installed and permissions to use it, type ``w ! sudo tee %'' to force a write. % You can adjust the volume of various parts of the sound system in your computer by typing 'mixer .volume=%'. To get a list of what you can adjust, just type 'mixer'. % You can automatically download and install binary packages by doing pkg install This will also automatically install the packages that are dependencies for the package you install (ie, the packages it needs in order to work.) % You can change the video mode on all consoles by adding something like the following to /etc/rc.conf: allscreens="80x30" You can use "vidcontrol -i mode | grep T" for a list of supported text modes. -- Konstantinos Konstantinidis % You can disable tcsh's terminal beep if you `set nobeep'. % You can install extra packages for FreeBSD by using the ports system. If you have installed it, you can download, compile, and install software by just typing # cd /usr/ports// # make install && make clean as root. The ports infrastructure will download the software, change it so it works on FreeBSD, compile it, install it, register the installation so it will be possible to automatically uninstall it, and clean out the temporary working space it used. You can remove an installed port you decide you do not want after all by typing # cd /usr/ports// # make deinstall as root. % You can look through a file in a nice text-based interface by typing less filename % You can make a log of your terminal session with script(1). % You can often get answers to your questions about FreeBSD by searching in the FreeBSD mailing list archives at https://lists.freebsd.org/search % You can open up a new split-screen window in (n)vi with :N or :E and then use ^w to switch between the two. % You can permanently set environment variables for your shell by putting them in a startup file for the shell. The name of the startup file varies depending on the shell - csh and tcsh uses .login, bash, sh, ksh and zsh use .profile. When using bash, sh, ksh or zsh, don't forget to export the variable. % You can press Ctrl-D to quickly exit from a shell, or logout from a login shell. -- Konstantinos Konstantinidis % You can press up-arrow or down-arrow to walk through a list of previous commands in tcsh. % You can search for documentation on a keyword by typing apropos keyword % You can `set autologout = 30' to have tcsh log you off automatically if you leave the shell idle for more than 30 minutes. % You can use aliases to decrease the amount of typing you need to do to get commands you commonly use. Examples of fairly popular aliases include (in -Bourne shell style, as in /bin/sh, bash, ksh, and zsh): +POSIX shell style, as in /bin/sh, bash, ksh, and zsh): alias lf="ls -FA" alias ll="ls -lA" alias su="su -m" In csh or tcsh, these would be alias lf ls -FA alias ll ls -lA alias su su -m To remove an alias, you can usually use 'unalias aliasname'. To list all aliases, you can usually type just 'alias'. % You can use /etc/make.conf to control the options used to compile software on this system. Example entries are in /usr/share/examples/etc/make.conf and in make.conf(5). For options that are set for building FreeBSD's kernel and its world, see src.conf(5). % You can use "pkg info" to see a list of packages you have installed. % You can use the 'fetch' command to retrieve files over ftp, http or https. fetch https://www.FreeBSD.org/images/beastie.png will download the beastie image from the FreeBSD web site. % You can use "whereis" to search standard binary, manual page and source directories for the specified programs. This can be particularly handy when you are trying to find where in the ports tree an application is. Try "whereis firefox" and "whereis whereis". -- Konstantinos Konstantinidis % Want to run the same command again? In many shells (e.g., tcsh, zsh, bash) you can type "!!". % Want to go the directory you were just in? Type "cd -" % Can't delete /usr/obj? Enter "chflags -R noschg /usr/obj" to remove the system immutable flag for all files in /usr/obj. -- Lars Engels % Want to list all files of an installed package? Enter "pkg info -l packagename". -- Lars Engels % Are you looking for a package? Search for it with "pkg search part_of_package_name" -- Lars Engels % If you want to recursively copy a directory preserving file and directory attributes use "cp -a source target" -- Lars Engels % Do you wonder what a terminal program is doing at the moment? dd(1) does not show any throughput? Hit "^T" (Control + t) to send SIGINFO to the process and see what it is doing. -- Lars Engels % Do you want to know which version of FreeBSD you are running? Enter "freebsd-version -ku" to display kernel and userland version. -- Lars Engels % If you want to end one or more processes at a time using a regular expression enter "pkill regex". -- Lars Engels % Do you want to run a program directly after some other process has ended? Use "pwait pid && new_program" -- Lars Engels % When you want your users to be able to reboot or shutdown FreeBSD, add them to the group "operator" and they are allowed to use shutdown(8) and poweroff(8). -- Lars Engels % If you need to create a FAT32 formatted USB thumb drive, find out its devicename running dmesg(8) after inserting it. Then create an MBR schema, a single slice and format it: # gpart create -s MBR ${devicename} # gpart add -t fat32 ${devicename} # newfs_msdos -F 32 -L thumbdrive ${devicename}s1 -- Lars Engels % If you want to get a sorted list of all services that are started when FreeBSD boots, enter "service -e". -- Lars Engels % To easily configure your installed FreeBSD use bsdconfig(8). -- Lars Engels % After you compiled and installed a new version of FreeBSD, use etcupdate(8) to merge configuration updates. Run "etcupdate extract" once when your sources match your running system, then run "etcupdate" after every upgrade and "etcupdate resolve" to resolve any conflicts. -- Lars Engels % Do you want to do a binary upgrade of your running FreeBSD installation? Use freebsd-update(8). To install updates and patches for the running branch use # freebsd-update fetch # freebsd-update install Then, to upgrade to a newer release use # freebsd-update upgrade -r ${name_of_release} -- Lars Engels % To run rc scripts in /etc/rc.d and /usr/local/etc/rc.d use service(8). Run "service ${name_of_rc_script} start" to start a daemon and "service ${name_of_rc_script} stop" to stop it. -- Lars Engels % If you don't want to edit /etc/rc.conf directly, use sysrc(8) to add and remove entries. Use "sysrc name=value" to add an entry and "sysrc -x name" to delete an entry. -- Lars Engels % You can upload the dmesg of your system to help developers get an overview of commonly used hardware and peripherals for FreeBSD. Use the curl package to upload it like this: curl -v -d "nickname=$USER" -d "description=FreeBSD/$(uname -m) on \ $(kenv smbios.system.maker) $(kenv smbios.system.product)" -d "do=add" \ --data-urlencode 'dmesg@/var/run/dmesg.boot' http://dmesgd.nycbug.org/index.cgi % Want to know how much memory (in bytes) your machine has installed? Let sysctl(8) tell you with the following command: sysctl hw.realmem The realmem value is memory before the kernel and modules are loaded, whereas hw.physmem is what is left after they were loaded. The number of active CPUs is displayed using this command: sysctl hw.ncpu -- Benedict Reuschling % When using ZFS as the file system the "df" command is reporting the pool size and not file system sizes. It also does not know about descendent ZFS datasets, snapshots, quotas, and reservations with their individual space usage. Use the built-in "zfs list" command to get a better overview of space usage: zfs list -o space -- Benedict Reuschling % To learn more about what your system is doing, take a look at systat(1). For example, to get various statistics related to virtual memory usage, process scheduling, device interrupts, system name translation caching, and disk I/O, enter the following: systat -vmstat Other values are icmp, icmp6, ifstat, iostat, ip, ip6, netstat, pigs, sctp, swap, tcp, or zarc. You can switch between displays using : and exit back to your shell by typing :quit -- Benedict Reuschling % To set a quota of 10 GB for the user named foo on a ZFS dataset, run the following command: # zfs set userquota@foo=10G pool/home/foo The zfs userspace command can display the quota and current space usage: # zfs userspace pool/home/foo To unset a quota, assign "none" as the value. -- Benedict Reuschling % ZFS can display I/O statistics for a given pool using the iostat subcommand. By default, it will display one line of current activity. To display stats every 5 seconds run the following command (cancel with CTRL+C): zpool iostat 5 To view individual disk activities, specify the -v parameter: zpool iostat -v Of course, both can be combined. For more options, see zpool(8). -- Benedict Reuschling % FreeBSD's top(1) utility displays CPU statistics by default. To display I/O activity for each process instead, run top like this: top -m io -- Benedict Reuschling % ZFS keeps a history of commands run against a specific pool using the history subcommand to zpool: zpool history More details are available using the -i and -l parameters. Note that ZFS will not keep the complete pool history forever and will remove older events in favor of never ones. -- Benedict Reuschling % To display the compression ratio for the ZFS dataset /var/log on the pool mypool, run the following command: zfs get refcompressratio mypool/var/log The refcompressratio will only display the compression ratio for that specific dataset, not the descendant datasets. To include the child datasets, the command looks like this: zfs get compressratio mypool/var -- Benedict Reuschling % You can limit the depth of the displayed datasets in the "zfs list" output using the -d parameter. To display only the first level of datasets below mypool/usr and not the ones deeper than those, run this command: zfs list -d 1 mypool/usr -- Benedict Reuschling % The "zfs list" command can be filtered in multiple ways. To display just the dataset name, use the -o parameter: zfs list -o name mypool/usr More columns and their order can be defined by separating them with commas: zfs list -o mountpoint,name,avail -- Benedict Reuschling % The output of "zfs list" can be sorted by a specific column using -s. To sort the datasets by the "used" column in ascending order, run this command: zfs list -s used To sort in descending order instead, use -S: zfs list -S used -- Benedict Reuschling % To make the "zfs list" output more script-friendly, you can suppress the output of the headers for each column by passing the -H parameter: zfs list -H Another helpful option for script writers is -p, which displays the numbers in non-rounded, exact values: zfs list -p -- Benedict Reuschling % Before deleting a dataset or snapshot, perform a dry run using the -n parameter. This is to make sure you really want to delete just that dataset/snapshot and not any dependent ones. ZFS will display the resulting action when -n is combined with the -v option without actually performing it: zfs destroy -nrv mypool@mysnap Once you are sure this is exactly what you intend to do, remove the -n parameter to execute the destroy operation. -- Benedict Reuschling % You can delete a range of ZFS snapshots (a-z) in multiple ways. The following will delete d and all earlier snapshots: zfs destroy mypool/data@%d To delete d and all later snapshots: zfs destroy mypool/data@d% To delete all dataset snapshots: zfs destroy mypool/data@% Make sure to let ZFS perform a dry run (-n option) first and display (-v) what it would do to confirm that the delete operation is removing exactly what you intended. -- Benedict Reuschling % To set a custom ZFS property on the mypool pool, you need to provide it using the "key1:key2=value" syntax, where the colon (:) is used as the separator and identifier from the built-in ZFS properties: # zfs set warranty:expires=2038-01-19 mypool The custom property is applied to all datasets and can be queried like any built-in properties using zfs get: zfs get warranty:expires mypool To reset the value of a custom property, use the inherit subcommand: # zfs inherit warranty:expires mypool Removing a custom property from a pool is done using the -r flag to the "zfs inherit" command: # zfs inherit -r warranty:expires mypool -- Benedict Reuschling % To delete a range of ZFS snapshots, use the % (percent) character after the full path to the first snapshot that should be included. For example, to simulate deleting snapshots a through (including) d, use this command: # zfs destroy -rvn mypool/tmp@a%d Once you are sure that this is what you want, remove the -n option: # zfs destroy -rv mypool/tmp@a%d -- Benedict Reuschling % You can prevent the removal of a ZFS snapshot by using the hold subcommand. For example, to prevent the snapshot called milestone from deletion, run the following command: # zfs hold milestone_hold mypool/projects@my_milestone The "zfs holds" command will list all current snapshots that are protected this way (-r for a recursive list): # zfs holds -r mypool The TIMESTAMP column in the output of the above command is from when the hold was created, not the snapshot it holds. The "zfs destroy" command will echo a "dataset is busy" message on the console when it encounters a hold. Use "zfs release" to release the hold on the snapshot: # zfs release milestone_hold mypool/projects@my_milestone -- Benedict Reuschling % A user "sender" needs the following permissions set to send a ZFS dataset: # zfs allow -u sender send,snapshot txpool On the receiving side, the user "receiver" requires these permissions: # zfs allow -u receiver compression,mountpoint,mount,create,receive rxpool -- Benedict Reuschling % Don't let your zpool fill up completely by creating a dataset with reservation. # zfs create -o refreservation=<5% of total pool space> /reserved You can always shrink the reserve if you need the space, but your pool will always have space left this way. -- Benedict Reuschling % Sometimes a single slow HDD can cripple the performance of your entire system. You can spot one like this: # gstat -I5s | sort -rn -k9 | head -- Alan Somers % FreeBSD's ps(1) can create a dependency tree based on parent/child relationships between processes, like this: $ ps -d -- Daniel Ebdrup Jensen % It is possible to measure the resident memory set: $ vmstat -o | awk 'NR>1 { t[$7] += $1 } \ END { for (i in t) printf "%s %d\n",i,t[i] }' The rows have the following meaning: df = default (not assigned a specific pager) sw = swap df = virtual vn = vnode ph = heap md = memory device This will be reported in number of pages, so it needs to be multiplied by the page size of the architecture which can be found via: $ sysctl -n hw.pagesize -- Daniel Ebdrup Jensen % To establish a serial connection to anything including a USB device, nothing more than cu(1) is needed: $ cu -s 115200 -l /dev/ttyU0 -- Daniel Ebdrup Jensen % You can control kernel stack(9) traces on ^T (tty info) by setting kern.tty_info_kstacks to 0 (off), 1 (on), or 2 (verbose), e.g.: # sysctl kern.tty_info_kstacks=2 -- Michael Gmelin % To determine which fonts provide a particular Unicode character, fc-list from the fontconfig package may be helpful. For example, if your friend complains that the emoji you sent won't display, run fc-list with the hex value of the character to determine which font your friend should install. $ fc-list ':charset=0x1F4A1' /usr/local/share/fonts/noto/NotoColorEmoji.ttf: Noto Color Emoji:style=Regular $ pkg which /usr/local/share/fonts/noto/NotoColorEmoji.ttf /usr/local/share/fonts/noto/NotoColorEmoji.ttf was installed by package noto-emoji-2.042 % When netstat reports every 8 seconds, it tells traffic in bits per second: $ netstat -I bge0 8 % Using vt(4) on a laptop? Try this sh(1) function. It provides an "h" command that prints the last 22 commands executed, the time, remaining battery life, and current working directory: h() { fc -l -22; printf "%s\n" "`date +%H:%M` -- `apm -l`% -- `pwd`"; } -- Alexander Ziaee % diff --git a/usr.bin/script/script.1 b/usr.bin/script/script.1 index 5f40e5af28ff..ef8eaa35174f 100644 --- a/usr.bin/script/script.1 +++ b/usr.bin/script/script.1 @@ -1,304 +1,304 @@ .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd October 26, 2022 .Dt SCRIPT 1 .Os .Sh NAME .Nm script .Nd make typescript of terminal session .Sh SYNOPSIS .Nm .Op Fl aeFfkqrw .Op Fl t Ar time .Op Ar file Op Ar command ... .Nm .Fl p .Op Fl deq .Op Fl T Ar fmt .Op Ar file .Sh DESCRIPTION The .Nm utility makes a typescript of everything printed on your terminal. It is useful for students who need a hardcopy record of an interactive session as proof of an assignment, as the typescript file can be printed out later with .Xr lpr 1 . .Pp If the argument .Ar file is given, .Nm saves all dialogue in .Ar file . If no file name is given, the typescript is saved in the file .Pa typescript . .Pp If the argument .Ar command is given, .Nm will run the specified command with an optional argument vector instead of an interactive shell. .Pp The following options are available: .Bl -tag -width "-F pipe" .It Fl a Append the output to .Ar file or .Pa typescript , retaining the prior contents. .It Fl d When playing back a session with the .Fl p flag, do not sleep between records when playing back a timestamped session. .It Fl e Accepted for compatibility with .Em util-linux .Nm . The child command exit status is always the exit status of .Nm . .It Fl F Immediately flush output after each write. This will allow a user to create a named pipe using .Xr mkfifo 1 and another user may watch the live session using a utility like .Xr cat 1 . .It Fl f Create .Ar file.filemon or .Pa typescript.filemon using .Xr filemon 4 . .It Fl k Log keys sent to the program as well as output. .It Fl p Play back a session recorded with the .Fl r flag in real time. .It Fl q Run in quiet mode, omit the start, stop and command status messages. .It Fl r Record a session with input, output, and timestamping. .It Fl t Ar time Specify the interval at which the script output file will be flushed to disk, in seconds. A value of 0 causes .Nm to flush after every character I/O event. The default interval is 30 seconds. .It Fl T Ar fmt Implies .Fl p , but just reports the time-stamp of each output. This is very useful for assessing the timing of events. .Pp If .Ar fmt does not contain any .Ql % characters, it indicates the default format: .Ql %n@ %s [%Y-%m-%d %T]%n , which is useful for both tools and humans to read, should be used. Note that time-stamps will only be output when different from the previous one. .It Fl w Forward terminal size changes on .Dv SIGWINCH . .El .Pp The script ends when the forked shell (or command) exits (a .Em control-D to exit -the Bourne shell +the POSIX shell .Pf ( Xr sh 1 ) , and .Em exit , .Em logout or .Em control-D (if .Em ignoreeof is not set) for the C-shell, .Xr csh 1 ) . .Pp Certain interactive commands, such as .Xr vi 1 , create garbage in the typescript file. The .Nm utility works best with commands that do not manipulate the screen. The results are meant to emulate a hardcopy terminal, not an addressable one. .Sh ENVIRONMENT The following environment variables are utilized by .Nm : .Bl -tag -width SCRIPT .It Ev SCRIPT The .Ev SCRIPT environment variable is added to the sub-shell. If .Ev SCRIPT already existed in the users environment, its value is overwritten within the sub-shell. The value of .Ev SCRIPT is the name of the .Ar typescript file. .It Ev SHELL If the variable .Ev SHELL exists, the shell forked by .Nm will be that shell. If .Ev SHELL -is not set, the Bourne shell +is not set, the POSIX shell is assumed. .Pq Most shells set this variable automatically . .El .Sh EXAMPLES Record a simple .Xr csh 1 session with no additional details like input, output, and timestamping: .Bd -literal -offset indent $ SHELL=/bin/csh script Script started, output file is typescript % date Tue Jan 5 15:08:10 UTC 2021 % exit exit Script done, output file is typescript .Ed .Pp Now, replay the session recorded in the previous example: .Bd -literal -offset indent $ cat ./typescript Script started on Tue Jan 5 15:08:08 2021 % date Tue Jan 5 15:08:10 UTC 2021 % exit exit Script done on Tue Jan 5 15:08:13 2021 .Ed .Pp Record a .Xr csh 1 session, but this time with additional details like timestamping: .Bd -literal -offset indent $ SHELL=/bin/csh script -r Script started, output file is typescript % date Tue Jan 5 15:17:11 UTC 2021 % exit exit Script done, output file is typescript .Ed .Pp In order to replay a sessions recorded with the .Fl r flag, it is necessary to specify .Fl p .Po .Xr cat 1 will not work because of all the aditional information stored in the session file .Pc . Also, let us use .Fl d to print the whole session at once: .Bd -literal -offset indent $ script -dp ./typescript Script started on Tue Jan 5 15:17:09 2021 % date Tue Jan 5 15:17:11 UTC 2021 % exit exit Script done on Tue Jan 5 15:17:14 2021 .Ed .Sh SEE ALSO .Xr csh 1 .Po for the .Em history mechanism .Pc , .Xr filemon 4 .Sh HISTORY The .Nm command appeared in .Bx 3.0 . .Pp The .Fl d , .Fl p and .Fl r options first appeared in .Nx 2.0 and were ported to .Fx 9.2 . .Sh BUGS The .Nm utility places .Sy everything in the log file, including linefeeds and backspaces. This is not what the naive user expects. .Pp It is not possible to specify a command without also naming the script file because of argument parsing compatibility issues. .Pp When running in .Fl k mode, echo cancelling is far from ideal. The slave terminal mode is checked for ECHO mode to check when to avoid manual echo logging. This does not work when the terminal is in a raw mode where the program being run is doing manual echo. .Pp If .Nm reads zero bytes from the terminal, it switches to a mode when it only attempts to read once a second until there is data to read. This prevents .Nm from spinning on zero-byte reads, but might cause a 1-second delay in processing of user input. diff --git a/usr.sbin/adduser/adduser.8 b/usr.sbin/adduser/adduser.8 index e21a7653f250..eacc12a8f3ce 100644 --- a/usr.sbin/adduser/adduser.8 +++ b/usr.sbin/adduser/adduser.8 @@ -1,487 +1,487 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 1995-1996 Wolfram Schneider . Berlin. .\" All rights reserved. .\" Copyright (c) 2002-2004 Michael Telahun Makonnen .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd December 1, 2024 .Dt ADDUSER 8 .Os .Sh NAME .Nm adduser .Nd command for adding new users .Sh SYNOPSIS .Nm .Op Fl CDENSZhq .Op Fl G Ar groups .Op Fl L Ar login_class .Op Fl M Ar mode .Op Fl d Ar partition .Op Fl f Ar file .Op Fl g Ar login_group .Op Fl k Ar dotdir .Op Fl m Ar message_file .Op Fl s Ar shell .Op Fl u Ar uid_start .Op Fl w Ar type .Sh DESCRIPTION The .Nm utility is a shell script, implemented around the .Xr pw 8 command, for adding new users. It creates passwd/group entries, a home directory, copies dotfiles and sends the new user a welcome message. On systems where the parent of home directory is a ZFS dataset, .Nm will create the home directory as a ZFS dataset by default, unless the system administrator specified otherwise. It supports two modes of operation. It may be used interactively at the command line to add one user at a time, or it may be directed to get the list of new users from a file and operate in batch mode without requiring any user interaction. .Sh RESTRICTIONS .Bl -tag -width indent .It username Login name. The user name is restricted to whatever .Xr pw 8 will accept. Generally this means it may contain only lowercase characters or digits but cannot begin with the .Ql - character. Maximum length is 16 characters. The reasons for this limit are historical. Given that people have traditionally wanted to break this limit for aesthetic reasons, it has never been of great importance to break such a basic fundamental parameter in .Ux . You can change .Dv UT_NAMESIZE in .In utmp.h and recompile the world; people have done this and it works, but you will have problems with any precompiled programs, or source that assumes the 8-character name limit, such as NIS. The NIS protocol mandates an 8-character username. If you need a longer login name for e-mail addresses, you can define an alias in .Pa /etc/mail/aliases . .It "full name" This is typically known as the gecos field and usually contains the user's full name. Additionally, it may contain a comma separated list of values such as office number and work and home phones. If the name contains an ampersand it will be replaced by the capitalized login name when displayed by other programs. The .Ql \&: character is not allowed. .It shell Unless the .Fl S argument is supplied only valid shells from the shell database .Pq Pa /etc/shells are allowed. In addition, either the base name or the full path of the shell may be supplied. .It UID Automatically generated or your choice. It must be less than 32000. .It "GID/login group" Automatically generated or your choice. It must be less than 32000. .It password You may choose an empty password, disable the password, use a randomly generated password or specify your own plaintext password, which will be encrypted before being stored in the user database. .El .Sh UNIQUE GROUPS Perhaps you are missing what .Em can be done with this scheme that falls apart with most other schemes. With each user in their own group, they can safely run with a umask of 002 instead of the usual 022 and create files in their home directory without worrying about others being able to change them. .Pp For a shared area you create a separate UID/GID, you place each person that should be able to access this area into that new group. .Pp This model of UID/GID administration allows far greater flexibility than lumping users into groups and having to muck with the umask when working in a shared area. .Pp I have been using this model for almost 10 years and found that it works for most situations, and has never gotten in the way. (Rod Grimes) .Sh CONFIGURATION The .Nm utility reads its configuration information from .Pa /etc/adduser.conf . If this file does not exist, it will use predefined defaults. While this file may be edited by hand, the safer option is to use the .Fl C command line argument. With this argument, .Nm will start interactive input, save the answers to its prompts in .Pa /etc/adduser.conf , and promptly exit without modifying the user database. Options specified on the command line will take precedence over any values saved in this file. .Sh OPTIONS .Bl -tag -width indent .It Fl C Create new configuration file and exit. This option is mutually exclusive with the .Fl f option. .It Fl d Ar partition Home partition. Default partition, under which all user directories will be located. The .Pa /nonexistent partition is considered special. The .Nm script will not create and populate a home directory by that name. Otherwise, by default it attempts to create a home directory. .It Fl D Do not attempt to create the home directory. .It Fl E Disable the account. This option will lock the account by prepending the string .Dq Li *LOCKED* to the password field. The account may be unlocked by the super-user with the .Xr pw 8 command: .Pp .D1 Nm pw Cm unlock Op Ar name | uid .It Fl f Ar file Get the list of accounts to create from .Ar file . If .Ar file is .Dq Fl , then get the list from standard input. If this option is specified, .Nm will operate in batch mode and will not seek any user input. If an error is encountered while processing an account, it will write a message to standard error and move to the next account. The format of the input file is described below. .It Fl g Ar login_group Normally, if no login group is specified, it is assumed to be the same as the username. This option makes .Ar login_group the default. .It Fl G Ar groups Space-separated list of additional groups. This option allows the user to specify additional groups to add users to. The user is a member of these groups in addition to their login group. .It Fl h Print a summary of options and exit. .It Fl k Ar directory Copy files from .Ar directory into the home directory of new users; .Pa dot.foo will be renamed to .Pa .foo . .It Fl L Ar login_class Set default login class. .It Fl m Ar file Send new users a welcome message from .Ar file . Specifying a value of .Cm no for .Ar file causes no message to be sent to new users. Please note that the message file can reference the internal variables of the .Nm script. .It Fl M Ar mode Create the home directory with permissions set to .Ar mode , modified by the current .Xr umask 2 . .It Fl N Do not read the default configuration file. .It Fl q Minimal user feedback. In particular, the random password will not be echoed to standard output. .It Fl s Ar shell Default shell for new users. The .Ar shell argument may be the base name of the shell or the full path. Unless the .Fl S argument is supplied the shell must exist in .Pa /etc/shells or be the special shell .Em nologin to be considered a valid shell. .It Fl S The existence or validity of the specified shell will not be checked. .It Fl u Ar uid Use UIDs from .Ar uid on up. .It Fl w Ar type Password type. The .Nm utility allows the user to specify what type of password to create. The .Ar type argument may have one of the following values: .Bl -tag -width ".Cm random" .It Cm no Disable the password. Instead of an encrypted string, the password field will contain a single .Ql * character. The user may not log in until the super-user manually enables the password. .It Cm none Use an empty string as the password. .It Cm yes Use a user-supplied string as the password. In interactive mode, the user will be prompted for the password. In batch mode, the last (10th) field in the line is assumed to be the password. .It Cm random Generate a random string and use it as a password. The password will be echoed to standard output. In addition, it will be available for inclusion in the message file in the .Va randompass variable. .El .It Fl Z Do not attempt to create ZFS home dataset. .El .Sh FORMAT When the .Fl f option is used, the account information must be stored in a specific format. All empty lines or lines beginning with a .Ql # will be ignored. All other lines must contain ten colon .Pq Ql \&: separated fields as described below. Command line options do not take precedence over values in the fields. Only the password field may contain a .Ql \&: character as part of the string. .Pp .Sm off .D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password .Sm on .Bl -tag -width ".Ar password" .It Ar name Login name. This field may not be empty. .It Ar uid Numeric login user ID. If this field is left empty, it will be automatically generated. .It Ar gid Numeric primary group ID. If this field is left empty, a group with the same name as the user name will be created and its GID will be used instead. .It Ar class Login class. This field may be left empty. .It Ar change Password ageing. This field denotes the password change date for the account. The format of this field is the same as the format of the .Fl p argument to .Xr pw 8 . It may be .Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy , where .Ar dd is for the day, .Ar mmm is for the month in numeric or alphabetical format: .Dq Li 10 or .Dq Li Oct , and .Ar yy Ns Op Ar yy is the four or two digit year. To denote a time relative to the current date the format is: .No + Ns Ar n Ns Op Ar mhdwoy , where .Ar n denotes a number, followed by the minutes, hours, days, weeks, months or years after which the password must be changed. This field may be left empty to turn it off. .It Ar expire Account expiration. This field denotes the expiry date of the account. The account may not be used after the specified date. The format of this field is the same as that for password ageing. This field may be left empty to turn it off. .It Ar gecos Full name and other extra information about the user. .It Ar home_dir Home directory. If this field is left empty, it will be automatically created by appending the username to the home partition. The .Pa /nonexistent home directory is considered special and is understood to mean that no home directory is to be created for the user. .It Ar shell Login shell. This field should contain either the base name or the full path to a valid login shell. .It Ar password User password. This field should contain a plaintext string, which will be encrypted before being placed in the user database. If the password type is .Cm yes and this field is empty, it is assumed the account will have an empty password. If the password type is .Cm random and this field is .Em not empty, its contents will be used as a password. This field will be ignored if the .Fl w option is used with a .Cm no or .Cm none argument. Be careful not to terminate this field with a closing .Ql \&: because it will be treated as part of the password. .El .Sh FILES .Bl -tag -width ".Pa /etc/adduser.message" -compact .It Pa /etc/master.passwd user database .It Pa /etc/group group database .It Pa /etc/shells shell database .It Pa /etc/login.conf login classes database .It Pa /etc/adduser.conf configuration file for .Nm .It Pa /etc/adduser.message message file for .Nm .It Pa /usr/share/skel skeletal login directory .It Pa /var/log/userlog logfile for .Nm .El .Sh SEE ALSO .Xr chpass 1 , .Xr passwd 1 , .Xr adduser.conf 5 , .Xr aliases 5 , .Xr group 5 , .Xr login.conf 5 , .Xr passwd 5 , .Xr shells 5 , .Xr pw 8 , .Xr pwd_mkdb 8 , .Xr rmuser 8 , .Xr vipw 8 , .Xr yp 8 .Sh HISTORY The .Nm command appeared in .Fx 2.1 . .Sh AUTHORS .An -nosplit This manual page and the original script, in Perl, was written by .An Wolfram Schneider Aq Mt wosch@FreeBSD.org . -The replacement script, written as a Bourne +The replacement script, written as a POSIX shell script with some enhancements, and the man page modification that came with it were done by .An Mike Makonnen Aq Mt mtm@identd.net . .Sh BUGS In order for .Nm to correctly expand variables such as .Va $username and .Va $randompass in the message sent to new users, it must let the shell evaluate each line of the message file. This means that shell commands can also be embedded in the message file. The .Nm utility attempts to mitigate the possibility of an attacker using this feature by refusing to evaluate the file if it is not owned and writable only by the root user. In addition, shell special characters and operators will have to be escaped when used in the message file. .Pp Also, password ageing and account expiry times are currently settable only in batch mode or when specified in .Pa /etc/adduser.conf . The user should be able to set them in interactive mode as well.