Managing users and groups on FreeBSD
SYNOPSIS
This document describes how to use FreeBSD's most commonly used tools for managing users, and explains some of the principles behind these tools.
The reader should be familiar with basic FreeBSD commands enough to be able to log into a FreeBSD server and get a shell prompt (either via telnet or ssh), change directories, list files, view files, and edit files.
Unless otherwise specified, all commands listed must be run as user root. If you do not have root access to your server, your options are limited to modifying your own account in certain, restricted ways (described in the appropriate sections below).
DESCRIPTION
This document will cover some of the basic commands that all FreeBSD system administrators should know about to manage users and groups.
Conventions
We use 'joe' as our example account on our system. We practice adding, modifying, and removing the 'joe' account in various ways.
Most of the time, the root user is executing commands to modify the 'joe' account. At these times, commands issued by root will appear with a hash (or pound sign: #) at the beginning of a line followed by a command:
# rmuser joe
This means that this command was issued by the root (super-user) user. This is a common convention in Unix documentation.
Likewise, a percent sign ('%') followed by a command is meant to indicate that the command was issued by a normal (unprivileged) user:
% passwd
This means that our example user 'joe' issued this command at his shell prompt.
Another convention we use in this document is manpage references. pw(8) means "the manpage named pw in section 8 of the manual". To read this manpage at your shell prompt, type:
# man 8 pw
Organization
This document is divided into the following sections:
Creating new users
Modifying existing users
Disabling existing users
Removing existing users
Managing users en-masse
Quotas
CREATING NEW USERS
The most common aspect of managing users on a FreeBSD system is adding new users to your system (sometimes called "provisioning"). The following programs are but a few of the ways to do this:
Adduser(8)
The simplest way to add a user to your system is with the adduser command (from the adduser(8) manpage):
Adduser is a simple program for adding new users.
Adduser checks the passwd, group and shell databases.
It creates passwd/group entries, HOME directory,
dotfiles and sends the new user a welcome message.
adduser works as a "wizard" (simple, step-by-step questions you answer). You can provide options to adduser to simplify the wizard interface even further. adduser is probably the most common way to add new users because of its simplicity. The -s and -q options removes some potentially confusing questions when adduser starts up:
# adduser -s -q
Use option ``-verbose'' if you want to see more warnings and questions
or try to repair bugs.
Enter username [^[a-z0-9_][a-z0-9_-]*$]: joe
Enter full name []: Joe Schmoe, Jr.
Enter shell bash csh date ksh ksh93 no sh tcsh zsh [sh]: bash
Enter home directory (full path) [/home/joe]:
Uid [1000]:
Enter login class: default []:
Login group joe [joe]:
Login group is ``joe''. Invite joe into other groups: guest no
[no]:
Enter password []:
Enter password again []:
Name: joe
Password: ****
Fullname: Joe Schmoe, Jr.
Uid: 1000
Gid: 1000 (joe)
Class:
Groups: joe
HOME: /home/joe
Shell: /usr/local/bin/bash
OK? (y/n) [y]:
Added user ``joe''
Add another user? (y/n) [y]: n
In this example, we enter a username 'joe', a full name 'Joe Schmoe, Jr.' and 'bash' for the shell. In all the rest of the questions, we simply hit Enter on our keyboard to specify that we want to accept the default value (found in square braces, e.g., [/home/joe]).
After entering the password (twice), adduser shows us a summary of what we are about to do and asks us to confirm this:
OK? (y/n) [y]:
at which prompt we hit Enter to confirm. We then see:
Add another user? (y/n) [y]:
at which prompt we reply n.
adduser has other configuration defaults you can specify in the /etc/adduser.conf file (adduser will even write this config file for you if you do not use the -q option). See the adduser(8) manpage for more details.
Pw(8)
Not far behind adduser in terms of ease-of-use is pw. While the pw(8) manpage is a bit daunting, once you become familiar with its consistent and powerful interface (and learn what options to ignore in the manpages due to differences in your own setup) you will probably prefer pw over adduser.
As an example of what options to ignore, unless you're running YP/NIS (a system comprised of network equivalents of passwd, group, hosts, and other common services), you can completely ignore the -Y and -y command-line options. Further, until you begin customizing policy information and default startup files for new users (advanced techniques not covered in this tutorial), you can ignore the -C, -D, -k, and -L options.
And unless you plan on setting account expiration policies (i.e., an account will expire, or a user's password will expire, forcing them to reset it), you can ignore the -e, and -p options.
This leaves us with a much simplified usage for pw(8):
pw useradd [name|uid] [-q] [-n name] [-u uid] [-c comment] [-N]
[-w method] [-g group] [-G grouplist] [-m] [-s shell] [-h fd] [-P]
These command-line options are likely the only ones you will use (unless you have more complex needs, of course, in which case the pw(8) manpage will be more useful to you).
Now we can look at a few examples of adding new accounts using pw.
A simple account for new user joe:
# pw user add -n joe -c "Joseph Schmoe, Jr." -m -h 0
Once entered, you will be prompted for the password, but only once (so type it carefully!), with something like this:
Password for user joe:
This will create a new user joe on your system with a unique UID (user id) and GID (group id). The -m option tells pw to create the home directory (which is what you usually want for new users). Some basic shell "skeleton" files will be copied into the user's home directory for him to customize at his leisure.
Notice that we can type user add as two words, or useradd as one word. The author prefers the former syntax because it helps him remember that user is interchangable with group, and add is interchangable with del, mod, and show.
Another simple account with a different shell and more secure password entry:
# pw user add -n joe -c "Joseph Schmoe, Jr." -m -s /usr/local/bin/bash
This will create a new user joe and give him bash as his default shell (good choice!). It will not prompt you for a password (notice the -h option is absent); as such, it creates an account that cannot be logged into. The next step you need to take to complete this account creation is to give joe a password. Do this using the passwd command:
# passwd joe
You will be prompted with the following (when you type passwords, they will not echo to the screen so that potential snoopers will not see it when you enter it, nor will they be able to scroll your terminal back to see it):
Changing local password for joe.
New password: (your password here)
Retype new password: (your password here)
passwd: updating the database...
passwd: done
Now Mr. Schmoe, Jr. can log into his account.
In our final example for adding accounts with pw, we introduce the -w command-line option. This is useful for creating random passwords at account creation time (often users choose bad passwords; pw can generate a random password that will be stronger than most others):
# pw user add -n joe -c "Joseph Schmoe, Jr." -m -s /bin/tcsh -w random
Password for 'joe' is: b7xUhHYq
This will create a user account for joe; a random password b7xUhHYq was generated and displayed on the screen. This could be sent via postal mail, telephone, encrypted email, or HTTPS to Joe Schmoe. Mr. Schmoe would memorize this password and use it to log into his account.
Vadduser(1) (For VPS V2 Products)
For VPS v2 products (a "virtually" dedicated FreeBSD server), the vadduser(1) command is available. This command is simpler to use than either adduser or pw. A manpage is available, which lists all available options and gives many examples of simple usage.
Generally, the more you supply on the command-line, the less the vadduser program has to prompt you for information. You can create a complete account without any interaction with the program beyond the command-line arguments:
vadduser --login=joe --fullname="Joe Schmoe" --password=joeiscool \
--services="ftp,mail,shell" --shell=tcsh --quota=50 --home=/home/joe
Of course, you can always use the "wizard" interface, which will prompt you with questions and describe what answers you should supply.
vadduser
This will prompt you step by step like adduser does; vadduser, however, asks fewer questions and adds more description of what's happening, as well as allows you to set service options (email, ftp, etc.) and quotas for new accounts.
MODIFYING EXISTING USERS
Once a user account has been added to your system, you can use several programs to modify that user's settings. In fact, some of these programs are also available for users to run themselves (from a shell prompt), further reducing the need for your direct intervention as system administrator.
Chpass(1)
chpass is a command useful for changing certain information in password files. If you run chpass as root, (e.g., chpass joe), an editor will open (e.g., pico, vi, emacs, ee, etc.) with the following information:
#Changing user database information for joe.
Login: joe
Password: $1$uAGNRKJP$4.JUH2Q.wftt9GiwBSsNL.
Uid [#]: 1002
Gid [# or name]: 1002
Change [month day year]:
Expire [month day year]:
Class:
Home directory: /home/joe
Shell: /usr/local/bin/bash
Full Name: Joseph Schmoe, Jr.
Office Location:
Office Phone:
Home Phone:
Other information:
The root user may change any of this information. If, on the other hand, you run chpass as the user (e.g., joe), you may only change a limited amount of information:
#Changing user database information for joe.
Shell: /usr/local/bin/bash
Full Name: Joseph Schmoe, Jr.
Office Location:
Office Phone:
Home Phone:
Other information:
That is, your shell and your "gecos" (full name, plus other info if desired) are the only things you may change when running chpass as the user.
chpass, despite its name, is usually not the program you want to run to change someone's password. For changing passwords, you should use passwd(1) instead.
Passwd(1)
passwd is the program to use to change a user's password. If you run passwd as root, (e.g., passwd joe), you will be prompted twice for the new password for user joe:
# passwd joe
Changing local password for joe.
New password:
Retype new password:
passwd: updating the database...
passwd: done
If passwd is run as the user (e.g., joe), you will be prompted for your old password first, then your new password. This is a security feature to prevent unauthorized users from changing user passwords from an unattended terminal:
% passwd
Changing local password for joe.
Old password:
New password:
Retype new password:
passwd: updating the database...
passwd: done
Once run, the password for joe will be the new password. Email, FTP, and shell access will all be gained with this new password for the joe account.
Pw(8)
Changing user account information interactively is best accomplished with either the chpass, or passwd commands. However, when you want a quick one-liner to fix an account, or if you need to automate account modification, pw is your program.
Note some of the interesting uses for pw:
Changing user's name:
# pw user mod joe -c "Joseph Carmichael Schmoe"
Changing user's password (be careful--it doesn't ask twice!):
# pw user mod joe -h 0
New password for user joe:
Changing user's login shell:
# pw user mod joe -s /usr/local/bin/tcsh
Adding a user to another group:
# pw user mod joe -G web
Removing a user from a group (in this case, the 'web' group):
# pw user mod joe -G joe
The -G option removes the user from all groups except the ones listed after -G (each group should be separated by commas).
Vedituser (For VPS V2 Products)
For VPS v2 products (a "virtually" dedicated FreeBSD server), the vedituser(1) command ins available. This command is simpler to use than pw, and safer to use than chpass. A manpage is available, which lists all available options and gives many examples of simple usage.
Like vadduser, the more you supply on the command-line, the less the vedituser program has to prompt you for information. By way of example:
vedituser --login=joe --services="ftp,mail"
will remove joe's shell access. You will be prompted for missing options, but the current account settings will be used as default values, so you can simply hit <Enter> to accept them.
DISABLING EXISTING USERS (BUT NOT REMOVING THEIR ACCOUNTS)
Disabling means many things to many people. Some people (including the author) would classify "disabling" as not only the inability to log in and do things, but also to shut off other existing services (such as cron, web, and other services that do not require the user to log in).
However, for the sake of space and time, we will define 'disabling' simply as the act of making a shell, ftp, and email (POP) account unavailable to the user. Disabling cron, web, and other services are beyond the scope of this tutorial, but are important considerations.
Pw(8)
The simplest way to disable an account is via the pw command:
# pw lock joe
The joe account has now been disabled. To re-enable, simply:
# pw unlock joe
Now the joe account is available for login again.
Chpass
Another effective, though slightly more error-prone method of disabling an account, is to insert an asterisk at the beginning of the user's password field. This is one of the few times you will use chpass as root to modify a password directly:
# chpass joe
#Changing user database information for joe.
Login: joe
Password: *$1$tmTYmsuQ$IHSy7urpdZwXEzA3iYsnF/
Note the asterisk ('*') at the beginning of the password hash. This guarantees that no password will match because the asterisk is outside the range of characters used by the password hashing algorithm.
When the time comes to re-enable the account, remove the asterisk using chpass.
Editing /Etc/Master.Passwd Directly
You may also disable the account by editing /etc/master.passwd directly. Like the chpass example above, insert an asterisk at the beginning of the password field. Be sure to run:
pwd_mkdb -p /etc/master.passwd
when you're done so your changes propagate to the other password databases.
Re-enabling the account is accomplished in an analogous way (and be sure to run pwd_mkdb again).
REMOVING EXISTING USERS
Removing users from your system is probably the simplest operation you will do. The command to run is called rmuser and it works like this:
# rmuser joe
This will prompt you with:
Matching password entry:
joe:$1$RzJXr6ka$xdE88TjW4vpwthy/.Vtho/:1004:1004::0:0:Joseph \
Carmichael Schmoe:/home/joe:/usr/local/bin/tcsh
Is this the entry you wish to remove?
at which you simply type a 'y' and enter. You will also be prompted to remove their home directory:
Remove user's home directory (/home/joe)?
If you reply affirmatively, the home directory will be completely removed. Otherwise, the directory will continue to exist, and you may do with it as you please (e.g., tar it up as an archive and then remove it, etc.).
If you know you want to remove everything, you can use the -y option for rmuser, which will answer 'y' automatically at all questions:
# rmuser -y joe
Updating password file, updating databases, done.
Updating group file: (removing group joe -- personal group is empty) done.
Removing user's home directory (/home/joe): done.
Removing user's incoming mail file /var/mail/joe: done.
Removing files belonging to joe from /tmp: done.
Removing files belonging to joe from /var/tmp: done.
Removing files belonging to joe from /var/tmp/vi.recover: done.
Removing existing users by hand will not be covered in this tutorial, except to say that the password file entry, group entries, home directory, mail spools, cron jobs, and other miscellaneous files need to be considered when removing users. rmuser does all of this for you (and does it well).
Using Pw
Of course, pw can also be used to remove user accounts:
# pw user del joe -r
The -r option is the inverse of -m. While -m instructs pw to create the home directory, -r tells pw to remove the home directory and its contents without prompting (much like rmuser with the -y option). pw is somewhat safer than rmuser; the pw(8) manpage tells us this about the -r option:
This tells pw to remove the user's home directory and all
of its contents. Pw errs on the side of caution when
removing files from the system. Firstly, it will not do so
if the uid of the account being removed is also used by
another account on the system, and the 'home' directory in
the password file is a valid path that commences with the
character `/'. Secondly, it will only remove files and
directories that are actually owned by the user, or sym-
bolic links owned by anyone under the user's home direc-
tory. Finally, after deleting all contents owned by the
user only empty directories will be removed. If any addi-
tional cleanup work is required, this is left to the admin-
istrator.
If you notice that a home directory was not removed, it was for one of the reaons stated above. You should check it out to see why before completely removing the home directory.
MANAGING USERS EN-MASSE
Large-scale management of users requires you to write a little code to get things done. Which programming language or environment you use is usually not important. However, some programming languages have been tailored for system administration and make automating common tasks simple. Among these are Perl and the Bourne-shell languages, which we will use here for our examples (many shells are Bourne-compatible to some degree, among them: ash, bash, sh, (the original Bourne shell), and zsh in Bourne-compatibility mode).
In this section, our sample task will be to add several hundred users to our system (with an intentional mistake affecting all accounts). Once the accounts have been provisioned, we will fix our mistakes so that all of our account owners are happy.
Creating Many Accounts
We want to create 300 accounts at once. Our saving grace is that the usernames do not have to be very creative (in fact, they can be downright ugly). We can do this using Perl:
#!/usr/local/bin/perl -w
use strict;
## create accounts for user_1 .. user_300
for my $n ( 1..300 ) {
system('pw', 'user', 'add', '-n', "user_$n");
}
We save this program in a file called create_users and type:
# perl create_users
After a few moments all of the accounts have been created. The account names are user_1, user_2, and so on. However, we just realized that we forgot to create the home directories for all these users! (We omitted the -m option after the username). Perl to the rescue again:
#!/usr/local/bin/perl -w
use strict;
## create home directories for user_1 .. user_300
for my $n ( 1..300 ) {
system('pw', 'user', 'mod', '-n', "user_$n", '-m');
}
We save this program in a file called modify_users and type:
# perl modify_users
After a few moments we check and, thankfully, all the home directories have now been created. You can see that our arguments to the pw program have changed in two places: we use mod instead of add, and we append the -m option after the username to create the home directory. We could change the shell in the same way, for example, by changing:
system('pw', 'user', 'mod', '-n', "user_$n", '-m');
to:
system('pw', 'user', 'mod', '-n', "user_$n", '-s', '/usr/local/bin/tcsh' );
Time passes. The need for these user accounts has disappeared. Is there a clean and sure-fire way to remove these accounts? Perl is our friend once again:
#!/usr/local/bin/perl -w
use strict;
## remove user_1 .. user_300 from our system
for my $n ( 1..300 ) {
system('pw', 'user', 'del', '-n', "user_$n", '-r');
}
We save this program in a file called remove_users and type:
# perl remove_users
After a few moments we notice that the accounts (password entries, group entries, home directories--everything) are gone. Nice!
The Bourne shell can also be used to accomplish these feats. In order for these one-liners to work, you need to be running a Bourne-compatible shell. The author recommends bash because of its completeness, but many people prefer the original /bin/sh for shell programming, which is always in good taste because of portability reasons (one Bourne-shell script is much more likely to run with no or few modifications than a csh or "C-shell" script).
You can run a Bourne shell by typing:
# exec /bin/sh
Creating 300 users
This one-liner will add 300 users and create their home directories:
# i=300; while [ $i -gt 0 ]; do pw user add -n "user_$i" -m; \
i=`expr $i - 1`; done
Modifying 300 users
This one-liner will modify all 300 accounts, changing their shells to the Bourne shell:
# i=300; while [ $i -gt 0 ]; do pw user mod -n "user_$i" \
-s /bin/sh; i=`expr $i - 1`; done
Deleting 300 users
This one-liner uses rmuser to remove the users from the system:
# i=300; while [ $i -gt 0 ]; do rmuser -y "user_$i"; \
i=`expr $i - 1`; done
You will see a lot of output from rmuser, however. To silence it (including errors), do this:
# i=300; while [ $i -gt 0 ]; do rmuser -y "user_$i" \
> /dev/null 2>&1; i=`expr $i - 1`; done
or use the pw command instead.
QUOTAS
Quotas enable you, the system administrator, to control how much disk space users consume. This helps prevent abuse to your system (in general, bad things happen when a disk is full) as well as enable you, if you are using your system for profit, to allot resources as needed.
Enabling Quotas
To enable quotas, open /etc/fstab in your favorite editor and make sure the mountpoint you want to enable quotas for has the userquota option set. For example, if your primary mountpoint (where your users' home directories reside) is /, you'll see:
# Device Mountpoint FStype Options
/dev/da0e / ufs rw
which becomes:
# Device Mountpoint FStype Options
/dev/da0e / ufs rw,userquota
Many systems use /usr or /home as mountpoints instead of /. In this case, you might see something like this:
# Device Mountpoint FStype Options Dump Pass#
/dev/ad0s1f /usr ufs rw 2 2
which becomes:
# Device Mountpoint FStype Options Dump Pass#
/dev/ad0s1f /usr ufs rw,userquota 2 2
Once you have added the userquota option (or if it is already present), save your file and return to your shell prompt.
Now you can type the following to enable quotas:
# quotaon -a
If you see a message like the following:
quotaon: using /usr/quota.user on
quotaon: /usr: Operation not supported
it means that your kernel has not been compiled to support quota operations. Compiling a new kernel is beyond the scope of this tutorial, but useful references may be found in the FreeBSD Handbook:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/quotas.html
Once quotas have been enabled, you're read to "prime" your quota database:
# quotacheck -a
This will crawl the filesystem once to initialize the quota database. Once completed, this operation should not need to be repeated unless you disable quotas (e.g., with quotaoff -a), when it will need to be run again once quotas are re-enabled.
NOTE: If you are using a VPS v2 product (a "virtually" dedicated FreeBSD server), you may simply run vadduser, vedituser, or vquota to enable quotas on your system. All of these steps will be done for you.
Setting Per-User Quotas
Now that your system is configured to allow quotas, we want to impose quota limits on users. This is accomplished in two ways:
via the edquota command:
As root, type edquota joe to edit the quota information for joe. An editor will open with the following information:
Quotas for user joe:
/: kbytes in use: 6, limits (soft = 0, hard = 0)
inodes in use: 10, limits (soft = 0, hard = 0)
Change soft = 0 and hard = 0 to the quota limit (in kilobytes) for the user. For example, if you want to impose a 10 megabyte limit on the joe account, change the limits to:
Quotas for user joe:
/: kbytes in use: 6, limits (soft = 10240, hard = 10240)
inodes in use: 10, limits (soft = 0, hard = 0)
See the edquota(8) manpage for more details and options with edquota.
via a programming interface (e.g., Perl):
Some systems come with Perl's Quota module already installed. To determine if you have it installed, type the following at your shell prompt:
# perl -MQuota
If you see no errors, and the cursor is now waiting for you to type more information, type a Ctrl-D to terminate perl.
However, if you see something like this:
Can't locate Quota.pm in @INC (@INC contains:
/usr/local/lib/perl5/5.6.1/i386-freebsd /usr/local/lib/perl5/5.6.1
/usr/local/lib/perl5/site_perl/5.6.1/i386-freebsd
/usr/local/lib/perl5/site_perl/5.6.1 /usr/local/lib/perl5/site_perl
/usr/local/lib/perl5/5.00503 /usr/local/lib/site_perl .).
it means you do not have the Quota module installed. To install it, try the following:
# perl -MCPAN -e 'install Quota'
Follow the CPAN instructions as they appear in your shell. Further assistance may be found in the CPAN(3) manpage, the Comprehensive Perl Archive Network interface.
Now that Perl's Quota module is installed, you can write a simple program to change a user's quota:
#!/usr/local/bin/perl -w
use strict;
use Quota;
## get the username from the command-line
my $user = shift or die "usage: set_quota <username> <kbytes>\n";
## find the uid for this user
my $uid = getpwnam($user);
## get the quota from the command-line
my $quota = shift;
## make sure a valid quota was entered
unless( defined $quota && $quota =~ /^\d+$/ ) {
die "usage: set_quota <username> <kbytes>\n";
}
print "Setting quota for $user...";
Quota::setqlim(Quota::getqcarg('/home'), $uid, $quota, $quota, 0, 0);
print "done\n";
exit;
We save this in a file called set_quota. If we want to use this often, we make the file executable:
# chmod 755 set_quota
Now we can run it anytime we want on any user. Let's give the joe account a 10 megabyte limit:
# ./set_quota joe 10240
Setting quota for joe...done
Let's login as joe and see if it worked:
# su - joe
% quota
Disk quotas for user joe (uid 1000):
Filesystem usage quota limit grace files quota limit grace
/ 6 10240 10240 10 0 0
% exit
Excellent! Now let's remove the quotas we gave joe:
# ./set_quota joe 0
Setting quota for joe...done
The joe account no longer has any filesystem quotas (you may login and verify this). Besides setting a limit on disk space usage, we can also limit the number of files a user can create. This involves setting the inodes in use paramter in edquota or setting the next two parameters in Quota's setqlim function (all left as an exercise for the reader).
using vquota (for VPS v2 products)
Simply type 'vquota' at your shell prompt to get a brief usage statement for vquota. To change joe's quota to 50 megabytes, we could type:
vquota joe 50
SUMMARY
FreeBSD supplies many useful commands to help system administrators manage user accounts. Chief among them are pw, adduser, passwd, and chpass. Knowing a shell or other programming language will also go a long way in automating routine and bulk tasks (including quota management).
The authoritative manual for FreeBSD system administration is The FreeBSD Handbook, found at:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
SEE ALSO
The FreeBSD Handbook:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
Managing users (from The FreeBSD Handbook):
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/users-modifying.html
Managing groups (from The FreeBSD Handbook):
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/users-groups.html
AUTHOR
Scott Wiersdorf, <scott@perlcode.org>
VERSION
$SMEId: docs/sysadmin/managing_users.pod,v 1.4 2003/07/18 22:21:21 scottw Exp $
SYNOPSIS
This document describes how to use FreeBSD's most commonly used tools for managing users, and explains some of the principles behind these tools.
The reader should be familiar with basic FreeBSD commands enough to be able to log into a FreeBSD server and get a shell prompt (either via telnet or ssh), change directories, list files, view files, and edit files.
Unless otherwise specified, all commands listed must be run as user root. If you do not have root access to your server, your options are limited to modifying your own account in certain, restricted ways (described in the appropriate sections below).
DESCRIPTION
This document will cover some of the basic commands that all FreeBSD system administrators should know about to manage users and groups.
Conventions
We use 'joe' as our example account on our system. We practice adding, modifying, and removing the 'joe' account in various ways.
Most of the time, the root user is executing commands to modify the 'joe' account. At these times, commands issued by root will appear with a hash (or pound sign: #) at the beginning of a line followed by a command:
# rmuser joe
This means that this command was issued by the root (super-user) user. This is a common convention in Unix documentation.
Likewise, a percent sign ('%') followed by a command is meant to indicate that the command was issued by a normal (unprivileged) user:
% passwd
This means that our example user 'joe' issued this command at his shell prompt.
Another convention we use in this document is manpage references. pw(8) means "the manpage named pw in section 8 of the manual". To read this manpage at your shell prompt, type:
# man 8 pw
Organization
This document is divided into the following sections:
Creating new users
Modifying existing users
Disabling existing users
Removing existing users
Managing users en-masse
Quotas
CREATING NEW USERS
The most common aspect of managing users on a FreeBSD system is adding new users to your system (sometimes called "provisioning"). The following programs are but a few of the ways to do this:
Adduser(8)
The simplest way to add a user to your system is with the adduser command (from the adduser(8) manpage):
Adduser is a simple program for adding new users.
Adduser checks the passwd, group and shell databases.
It creates passwd/group entries, HOME directory,
dotfiles and sends the new user a welcome message.
adduser works as a "wizard" (simple, step-by-step questions you answer). You can provide options to adduser to simplify the wizard interface even further. adduser is probably the most common way to add new users because of its simplicity. The -s and -q options removes some potentially confusing questions when adduser starts up:
# adduser -s -q
Use option ``-verbose'' if you want to see more warnings and questions
or try to repair bugs.
Enter username [^[a-z0-9_][a-z0-9_-]*$]: joe
Enter full name []: Joe Schmoe, Jr.
Enter shell bash csh date ksh ksh93 no sh tcsh zsh [sh]: bash
Enter home directory (full path) [/home/joe]:
Uid [1000]:
Enter login class: default []:
Login group joe [joe]:
Login group is ``joe''. Invite joe into other groups: guest no
[no]:
Enter password []:
Enter password again []:
Name: joe
Password: ****
Fullname: Joe Schmoe, Jr.
Uid: 1000
Gid: 1000 (joe)
Class:
Groups: joe
HOME: /home/joe
Shell: /usr/local/bin/bash
OK? (y/n) [y]:
Added user ``joe''
Add another user? (y/n) [y]: n
In this example, we enter a username 'joe', a full name 'Joe Schmoe, Jr.' and 'bash' for the shell. In all the rest of the questions, we simply hit Enter on our keyboard to specify that we want to accept the default value (found in square braces, e.g., [/home/joe]).
After entering the password (twice), adduser shows us a summary of what we are about to do and asks us to confirm this:
OK? (y/n) [y]:
at which prompt we hit Enter to confirm. We then see:
Add another user? (y/n) [y]:
at which prompt we reply n.
adduser has other configuration defaults you can specify in the /etc/adduser.conf file (adduser will even write this config file for you if you do not use the -q option). See the adduser(8) manpage for more details.
Pw(8)
Not far behind adduser in terms of ease-of-use is pw. While the pw(8) manpage is a bit daunting, once you become familiar with its consistent and powerful interface (and learn what options to ignore in the manpages due to differences in your own setup) you will probably prefer pw over adduser.
As an example of what options to ignore, unless you're running YP/NIS (a system comprised of network equivalents of passwd, group, hosts, and other common services), you can completely ignore the -Y and -y command-line options. Further, until you begin customizing policy information and default startup files for new users (advanced techniques not covered in this tutorial), you can ignore the -C, -D, -k, and -L options.
And unless you plan on setting account expiration policies (i.e., an account will expire, or a user's password will expire, forcing them to reset it), you can ignore the -e, and -p options.
This leaves us with a much simplified usage for pw(8):
pw useradd [name|uid] [-q] [-n name] [-u uid] [-c comment] [-N]
[-w method] [-g group] [-G grouplist] [-m] [-s shell] [-h fd] [-P]
These command-line options are likely the only ones you will use (unless you have more complex needs, of course, in which case the pw(8) manpage will be more useful to you).
Now we can look at a few examples of adding new accounts using pw.
A simple account for new user joe:
# pw user add -n joe -c "Joseph Schmoe, Jr." -m -h 0
Once entered, you will be prompted for the password, but only once (so type it carefully!), with something like this:
Password for user joe:
This will create a new user joe on your system with a unique UID (user id) and GID (group id). The -m option tells pw to create the home directory (which is what you usually want for new users). Some basic shell "skeleton" files will be copied into the user's home directory for him to customize at his leisure.
Notice that we can type user add as two words, or useradd as one word. The author prefers the former syntax because it helps him remember that user is interchangable with group, and add is interchangable with del, mod, and show.
Another simple account with a different shell and more secure password entry:
# pw user add -n joe -c "Joseph Schmoe, Jr." -m -s /usr/local/bin/bash
This will create a new user joe and give him bash as his default shell (good choice!). It will not prompt you for a password (notice the -h option is absent); as such, it creates an account that cannot be logged into. The next step you need to take to complete this account creation is to give joe a password. Do this using the passwd command:
# passwd joe
You will be prompted with the following (when you type passwords, they will not echo to the screen so that potential snoopers will not see it when you enter it, nor will they be able to scroll your terminal back to see it):
Changing local password for joe.
New password: (your password here)
Retype new password: (your password here)
passwd: updating the database...
passwd: done
Now Mr. Schmoe, Jr. can log into his account.
In our final example for adding accounts with pw, we introduce the -w command-line option. This is useful for creating random passwords at account creation time (often users choose bad passwords; pw can generate a random password that will be stronger than most others):
# pw user add -n joe -c "Joseph Schmoe, Jr." -m -s /bin/tcsh -w random
Password for 'joe' is: b7xUhHYq
This will create a user account for joe; a random password b7xUhHYq was generated and displayed on the screen. This could be sent via postal mail, telephone, encrypted email, or HTTPS to Joe Schmoe. Mr. Schmoe would memorize this password and use it to log into his account.
Vadduser(1) (For VPS V2 Products)
For VPS v2 products (a "virtually" dedicated FreeBSD server), the vadduser(1) command is available. This command is simpler to use than either adduser or pw. A manpage is available, which lists all available options and gives many examples of simple usage.
Generally, the more you supply on the command-line, the less the vadduser program has to prompt you for information. You can create a complete account without any interaction with the program beyond the command-line arguments:
vadduser --login=joe --fullname="Joe Schmoe" --password=joeiscool \
--services="ftp,mail,shell" --shell=tcsh --quota=50 --home=/home/joe
Of course, you can always use the "wizard" interface, which will prompt you with questions and describe what answers you should supply.
vadduser
This will prompt you step by step like adduser does; vadduser, however, asks fewer questions and adds more description of what's happening, as well as allows you to set service options (email, ftp, etc.) and quotas for new accounts.
MODIFYING EXISTING USERS
Once a user account has been added to your system, you can use several programs to modify that user's settings. In fact, some of these programs are also available for users to run themselves (from a shell prompt), further reducing the need for your direct intervention as system administrator.
Chpass(1)
chpass is a command useful for changing certain information in password files. If you run chpass as root, (e.g., chpass joe), an editor will open (e.g., pico, vi, emacs, ee, etc.) with the following information:
#Changing user database information for joe.
Login: joe
Password: $1$uAGNRKJP$4.JUH2Q.wftt9GiwBSsNL.
Uid [#]: 1002
Gid [# or name]: 1002
Change [month day year]:
Expire [month day year]:
Class:
Home directory: /home/joe
Shell: /usr/local/bin/bash
Full Name: Joseph Schmoe, Jr.
Office Location:
Office Phone:
Home Phone:
Other information:
The root user may change any of this information. If, on the other hand, you run chpass as the user (e.g., joe), you may only change a limited amount of information:
#Changing user database information for joe.
Shell: /usr/local/bin/bash
Full Name: Joseph Schmoe, Jr.
Office Location:
Office Phone:
Home Phone:
Other information:
That is, your shell and your "gecos" (full name, plus other info if desired) are the only things you may change when running chpass as the user.
chpass, despite its name, is usually not the program you want to run to change someone's password. For changing passwords, you should use passwd(1) instead.
Passwd(1)
passwd is the program to use to change a user's password. If you run passwd as root, (e.g., passwd joe), you will be prompted twice for the new password for user joe:
# passwd joe
Changing local password for joe.
New password:
Retype new password:
passwd: updating the database...
passwd: done
If passwd is run as the user (e.g., joe), you will be prompted for your old password first, then your new password. This is a security feature to prevent unauthorized users from changing user passwords from an unattended terminal:
% passwd
Changing local password for joe.
Old password:
New password:
Retype new password:
passwd: updating the database...
passwd: done
Once run, the password for joe will be the new password. Email, FTP, and shell access will all be gained with this new password for the joe account.
Pw(8)
Changing user account information interactively is best accomplished with either the chpass, or passwd commands. However, when you want a quick one-liner to fix an account, or if you need to automate account modification, pw is your program.
Note some of the interesting uses for pw:
Changing user's name:
# pw user mod joe -c "Joseph Carmichael Schmoe"
Changing user's password (be careful--it doesn't ask twice!):
# pw user mod joe -h 0
New password for user joe:
Changing user's login shell:
# pw user mod joe -s /usr/local/bin/tcsh
Adding a user to another group:
# pw user mod joe -G web
Removing a user from a group (in this case, the 'web' group):
# pw user mod joe -G joe
The -G option removes the user from all groups except the ones listed after -G (each group should be separated by commas).
Vedituser (For VPS V2 Products)
For VPS v2 products (a "virtually" dedicated FreeBSD server), the vedituser(1) command ins available. This command is simpler to use than pw, and safer to use than chpass. A manpage is available, which lists all available options and gives many examples of simple usage.
Like vadduser, the more you supply on the command-line, the less the vedituser program has to prompt you for information. By way of example:
vedituser --login=joe --services="ftp,mail"
will remove joe's shell access. You will be prompted for missing options, but the current account settings will be used as default values, so you can simply hit <Enter> to accept them.
DISABLING EXISTING USERS (BUT NOT REMOVING THEIR ACCOUNTS)
Disabling means many things to many people. Some people (including the author) would classify "disabling" as not only the inability to log in and do things, but also to shut off other existing services (such as cron, web, and other services that do not require the user to log in).
However, for the sake of space and time, we will define 'disabling' simply as the act of making a shell, ftp, and email (POP) account unavailable to the user. Disabling cron, web, and other services are beyond the scope of this tutorial, but are important considerations.
Pw(8)
The simplest way to disable an account is via the pw command:
# pw lock joe
The joe account has now been disabled. To re-enable, simply:
# pw unlock joe
Now the joe account is available for login again.
Chpass
Another effective, though slightly more error-prone method of disabling an account, is to insert an asterisk at the beginning of the user's password field. This is one of the few times you will use chpass as root to modify a password directly:
# chpass joe
#Changing user database information for joe.
Login: joe
Password: *$1$tmTYmsuQ$IHSy7urpdZwXEzA3iYsnF/
Note the asterisk ('*') at the beginning of the password hash. This guarantees that no password will match because the asterisk is outside the range of characters used by the password hashing algorithm.
When the time comes to re-enable the account, remove the asterisk using chpass.
Editing /Etc/Master.Passwd Directly
You may also disable the account by editing /etc/master.passwd directly. Like the chpass example above, insert an asterisk at the beginning of the password field. Be sure to run:
pwd_mkdb -p /etc/master.passwd
when you're done so your changes propagate to the other password databases.
Re-enabling the account is accomplished in an analogous way (and be sure to run pwd_mkdb again).
REMOVING EXISTING USERS
Removing users from your system is probably the simplest operation you will do. The command to run is called rmuser and it works like this:
# rmuser joe
This will prompt you with:
Matching password entry:
joe:$1$RzJXr6ka$xdE88TjW4vpwthy/.Vtho/:1004:1004::0:0:Joseph \
Carmichael Schmoe:/home/joe:/usr/local/bin/tcsh
Is this the entry you wish to remove?
at which you simply type a 'y' and enter. You will also be prompted to remove their home directory:
Remove user's home directory (/home/joe)?
If you reply affirmatively, the home directory will be completely removed. Otherwise, the directory will continue to exist, and you may do with it as you please (e.g., tar it up as an archive and then remove it, etc.).
If you know you want to remove everything, you can use the -y option for rmuser, which will answer 'y' automatically at all questions:
# rmuser -y joe
Updating password file, updating databases, done.
Updating group file: (removing group joe -- personal group is empty) done.
Removing user's home directory (/home/joe): done.
Removing user's incoming mail file /var/mail/joe: done.
Removing files belonging to joe from /tmp: done.
Removing files belonging to joe from /var/tmp: done.
Removing files belonging to joe from /var/tmp/vi.recover: done.
Removing existing users by hand will not be covered in this tutorial, except to say that the password file entry, group entries, home directory, mail spools, cron jobs, and other miscellaneous files need to be considered when removing users. rmuser does all of this for you (and does it well).
Using Pw
Of course, pw can also be used to remove user accounts:
# pw user del joe -r
The -r option is the inverse of -m. While -m instructs pw to create the home directory, -r tells pw to remove the home directory and its contents without prompting (much like rmuser with the -y option). pw is somewhat safer than rmuser; the pw(8) manpage tells us this about the -r option:
This tells pw to remove the user's home directory and all
of its contents. Pw errs on the side of caution when
removing files from the system. Firstly, it will not do so
if the uid of the account being removed is also used by
another account on the system, and the 'home' directory in
the password file is a valid path that commences with the
character `/'. Secondly, it will only remove files and
directories that are actually owned by the user, or sym-
bolic links owned by anyone under the user's home direc-
tory. Finally, after deleting all contents owned by the
user only empty directories will be removed. If any addi-
tional cleanup work is required, this is left to the admin-
istrator.
If you notice that a home directory was not removed, it was for one of the reaons stated above. You should check it out to see why before completely removing the home directory.
MANAGING USERS EN-MASSE
Large-scale management of users requires you to write a little code to get things done. Which programming language or environment you use is usually not important. However, some programming languages have been tailored for system administration and make automating common tasks simple. Among these are Perl and the Bourne-shell languages, which we will use here for our examples (many shells are Bourne-compatible to some degree, among them: ash, bash, sh, (the original Bourne shell), and zsh in Bourne-compatibility mode).
In this section, our sample task will be to add several hundred users to our system (with an intentional mistake affecting all accounts). Once the accounts have been provisioned, we will fix our mistakes so that all of our account owners are happy.
Creating Many Accounts
We want to create 300 accounts at once. Our saving grace is that the usernames do not have to be very creative (in fact, they can be downright ugly). We can do this using Perl:
#!/usr/local/bin/perl -w
use strict;
## create accounts for user_1 .. user_300
for my $n ( 1..300 ) {
system('pw', 'user', 'add', '-n', "user_$n");
}
We save this program in a file called create_users and type:
# perl create_users
After a few moments all of the accounts have been created. The account names are user_1, user_2, and so on. However, we just realized that we forgot to create the home directories for all these users! (We omitted the -m option after the username). Perl to the rescue again:
#!/usr/local/bin/perl -w
use strict;
## create home directories for user_1 .. user_300
for my $n ( 1..300 ) {
system('pw', 'user', 'mod', '-n', "user_$n", '-m');
}
We save this program in a file called modify_users and type:
# perl modify_users
After a few moments we check and, thankfully, all the home directories have now been created. You can see that our arguments to the pw program have changed in two places: we use mod instead of add, and we append the -m option after the username to create the home directory. We could change the shell in the same way, for example, by changing:
system('pw', 'user', 'mod', '-n', "user_$n", '-m');
to:
system('pw', 'user', 'mod', '-n', "user_$n", '-s', '/usr/local/bin/tcsh' );
Time passes. The need for these user accounts has disappeared. Is there a clean and sure-fire way to remove these accounts? Perl is our friend once again:
#!/usr/local/bin/perl -w
use strict;
## remove user_1 .. user_300 from our system
for my $n ( 1..300 ) {
system('pw', 'user', 'del', '-n', "user_$n", '-r');
}
We save this program in a file called remove_users and type:
# perl remove_users
After a few moments we notice that the accounts (password entries, group entries, home directories--everything) are gone. Nice!
The Bourne shell can also be used to accomplish these feats. In order for these one-liners to work, you need to be running a Bourne-compatible shell. The author recommends bash because of its completeness, but many people prefer the original /bin/sh for shell programming, which is always in good taste because of portability reasons (one Bourne-shell script is much more likely to run with no or few modifications than a csh or "C-shell" script).
You can run a Bourne shell by typing:
# exec /bin/sh
Creating 300 users
This one-liner will add 300 users and create their home directories:
# i=300; while [ $i -gt 0 ]; do pw user add -n "user_$i" -m; \
i=`expr $i - 1`; done
Modifying 300 users
This one-liner will modify all 300 accounts, changing their shells to the Bourne shell:
# i=300; while [ $i -gt 0 ]; do pw user mod -n "user_$i" \
-s /bin/sh; i=`expr $i - 1`; done
Deleting 300 users
This one-liner uses rmuser to remove the users from the system:
# i=300; while [ $i -gt 0 ]; do rmuser -y "user_$i"; \
i=`expr $i - 1`; done
You will see a lot of output from rmuser, however. To silence it (including errors), do this:
# i=300; while [ $i -gt 0 ]; do rmuser -y "user_$i" \
> /dev/null 2>&1; i=`expr $i - 1`; done
or use the pw command instead.
QUOTAS
Quotas enable you, the system administrator, to control how much disk space users consume. This helps prevent abuse to your system (in general, bad things happen when a disk is full) as well as enable you, if you are using your system for profit, to allot resources as needed.
Enabling Quotas
To enable quotas, open /etc/fstab in your favorite editor and make sure the mountpoint you want to enable quotas for has the userquota option set. For example, if your primary mountpoint (where your users' home directories reside) is /, you'll see:
# Device Mountpoint FStype Options
/dev/da0e / ufs rw
which becomes:
# Device Mountpoint FStype Options
/dev/da0e / ufs rw,userquota
Many systems use /usr or /home as mountpoints instead of /. In this case, you might see something like this:
# Device Mountpoint FStype Options Dump Pass#
/dev/ad0s1f /usr ufs rw 2 2
which becomes:
# Device Mountpoint FStype Options Dump Pass#
/dev/ad0s1f /usr ufs rw,userquota 2 2
Once you have added the userquota option (or if it is already present), save your file and return to your shell prompt.
Now you can type the following to enable quotas:
# quotaon -a
If you see a message like the following:
quotaon: using /usr/quota.user on
quotaon: /usr: Operation not supported
it means that your kernel has not been compiled to support quota operations. Compiling a new kernel is beyond the scope of this tutorial, but useful references may be found in the FreeBSD Handbook:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/quotas.html
Once quotas have been enabled, you're read to "prime" your quota database:
# quotacheck -a
This will crawl the filesystem once to initialize the quota database. Once completed, this operation should not need to be repeated unless you disable quotas (e.g., with quotaoff -a), when it will need to be run again once quotas are re-enabled.
NOTE: If you are using a VPS v2 product (a "virtually" dedicated FreeBSD server), you may simply run vadduser, vedituser, or vquota to enable quotas on your system. All of these steps will be done for you.
Setting Per-User Quotas
Now that your system is configured to allow quotas, we want to impose quota limits on users. This is accomplished in two ways:
via the edquota command:
As root, type edquota joe to edit the quota information for joe. An editor will open with the following information:
Quotas for user joe:
/: kbytes in use: 6, limits (soft = 0, hard = 0)
inodes in use: 10, limits (soft = 0, hard = 0)
Change soft = 0 and hard = 0 to the quota limit (in kilobytes) for the user. For example, if you want to impose a 10 megabyte limit on the joe account, change the limits to:
Quotas for user joe:
/: kbytes in use: 6, limits (soft = 10240, hard = 10240)
inodes in use: 10, limits (soft = 0, hard = 0)
See the edquota(8) manpage for more details and options with edquota.
via a programming interface (e.g., Perl):
Some systems come with Perl's Quota module already installed. To determine if you have it installed, type the following at your shell prompt:
# perl -MQuota
If you see no errors, and the cursor is now waiting for you to type more information, type a Ctrl-D to terminate perl.
However, if you see something like this:
Can't locate Quota.pm in @INC (@INC contains:
/usr/local/lib/perl5/5.6.1/i386-freebsd /usr/local/lib/perl5/5.6.1
/usr/local/lib/perl5/site_perl/5.6.1/i386-freebsd
/usr/local/lib/perl5/site_perl/5.6.1 /usr/local/lib/perl5/site_perl
/usr/local/lib/perl5/5.00503 /usr/local/lib/site_perl .).
it means you do not have the Quota module installed. To install it, try the following:
# perl -MCPAN -e 'install Quota'
Follow the CPAN instructions as they appear in your shell. Further assistance may be found in the CPAN(3) manpage, the Comprehensive Perl Archive Network interface.
Now that Perl's Quota module is installed, you can write a simple program to change a user's quota:
#!/usr/local/bin/perl -w
use strict;
use Quota;
## get the username from the command-line
my $user = shift or die "usage: set_quota <username> <kbytes>\n";
## find the uid for this user
my $uid = getpwnam($user);
## get the quota from the command-line
my $quota = shift;
## make sure a valid quota was entered
unless( defined $quota && $quota =~ /^\d+$/ ) {
die "usage: set_quota <username> <kbytes>\n";
}
print "Setting quota for $user...";
Quota::setqlim(Quota::getqcarg('/home'), $uid, $quota, $quota, 0, 0);
print "done\n";
exit;
We save this in a file called set_quota. If we want to use this often, we make the file executable:
# chmod 755 set_quota
Now we can run it anytime we want on any user. Let's give the joe account a 10 megabyte limit:
# ./set_quota joe 10240
Setting quota for joe...done
Let's login as joe and see if it worked:
# su - joe
% quota
Disk quotas for user joe (uid 1000):
Filesystem usage quota limit grace files quota limit grace
/ 6 10240 10240 10 0 0
% exit
Excellent! Now let's remove the quotas we gave joe:
# ./set_quota joe 0
Setting quota for joe...done
The joe account no longer has any filesystem quotas (you may login and verify this). Besides setting a limit on disk space usage, we can also limit the number of files a user can create. This involves setting the inodes in use paramter in edquota or setting the next two parameters in Quota's setqlim function (all left as an exercise for the reader).
using vquota (for VPS v2 products)
Simply type 'vquota' at your shell prompt to get a brief usage statement for vquota. To change joe's quota to 50 megabytes, we could type:
vquota joe 50
SUMMARY
FreeBSD supplies many useful commands to help system administrators manage user accounts. Chief among them are pw, adduser, passwd, and chpass. Knowing a shell or other programming language will also go a long way in automating routine and bulk tasks (including quota management).
The authoritative manual for FreeBSD system administration is The FreeBSD Handbook, found at:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
SEE ALSO
The FreeBSD Handbook:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
Managing users (from The FreeBSD Handbook):
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/users-modifying.html
Managing groups (from The FreeBSD Handbook):
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/users-groups.html
AUTHOR
Scott Wiersdorf, <scott@perlcode.org>
VERSION
$SMEId: docs/sysadmin/managing_users.pod,v 1.4 2003/07/18 22:21:21 scottw Exp $
No comments:
Post a Comment