Daemon News 199905 : User Management

User Management

Copyright © 1999 Dannyman

INTRODUCTION

This article is written partly as a how-to, and partly as an explanation of a little more than the average FreeBSD user would want to know about the FreeBSD user management system. While it goes into more gory details than you might want to know, it is written with the new user in mind. If you want to savour every detail and come to grok user management system in all its glory, read this thing the whole way through, then read all the related man pages, and then delve into the code. If you just want to add users right away, skip down to the section on pw. I'm guessing most readers will be somewhere in the middle, and will browse through the first few parts with varying degrees of interest.

GRITTY DETAILS

If all you want to do is add users, then skip on to the next part. If you want to have a basic understanding of how the password system works, slog through here.

The process of adding a user to a FreeBSD system comes in three steps:

1) Add an entry for user in /etc/master.passwd.
2) Update the system user databases.
3) Create a home directory for user.

The master.passwd file is where user information and passwords are stored and maintained. This is a text file, and each line describes a user as a series of ten colon separated fields. This file is edited by programs like chfn and passwd to update user data, and by the system administrator when adding or removing users or making other changes.

In order for FreeBSD to access information on users, the master.passwd file is copied into two system databases. This allows the system to access user information faster through a database than a text file, and it gives the administrator something to work on besides the "live" system. If an error is made when editing the master.passwd file, this error may be caught by pwd_mkdb, the program which generates the database files.

Why two system databases, you might ask yourself? The master.passwd file contains encrypted passwords for each user. For this reason only root can read it. If anyone could read it, anyone could run a password-cracking program and have a decent hope of eventually guessing a few passwords, thus gaining access to other peoples' accounts. When the databases are built, two separate copies are made - one database has all the user information, except passwords, and is accessible by the whole system. The other is the "secure" database, which contains everything in the other database but with passwords as well. This database, like the master.passwd file, is readable only by root, and is used by programs like login to verify that a user's password is correct.

Additionally, pwd_mkdb usually generates another file called, simply enough, passwd. This file is readable by everyone, and contains all the stuff found in master.passwd except for the passwords. The reason this file is created is because on some other Unix systems, this file has the role that master.passwd has on FreeBSD. Since some users and programs may expect to be able to read a file with user information called passwd, FreeBSD keeps the root-only version of passwd in a different place, and provides the traditional, readable passwd file, minus encrypted passwords, in its traditional spot.

Confused yet? Here's a summary:

/etc/master.passwd - user data and passwords, text, root only, "master" file
/etc/spwd.db - user data and passwords, system database, root only
/etc/pwd.db - user data, no passwords, public system database
/etc/passwd - user data, no passwords, public text for compatability

THE HARD WAY: vipw

Alright, you want to add a user to the system. Let's review the three steps you probably skipped in PART I:

1) Add an entry for user in /etc/master.passwd.
2) Update the system user databases.
3) Create a home directory for user.

You want to add a user the hard way? Go to your root prompt and enter the vipw command. Assuming you have set your EDITOR environment variable to something you're comfortable with, you should find yourself presented with several rows of user accounts, stored as a series of colon-separated fields. At this point you could either RTFM - man 5 passwd, or you could bear with my explanation here.

Start at the top. You should see something like:

root:r3dbpPtFuaZlQ:0:0::0:0:Charlie &:/root:/bin/csh

Those fields, read in order:

1) username
2) encrypted password
3) Numeric User ID
4) Numeric Group ID
5) User's login class
6) Password's expiration time
7) Account's expiration time
8) User's "full name"
9) User's home directory
10) User's login shell

The important bits you want to consider here are that username and numeric user ID, UID, should both be unique and tied directly to each other. In this case, root has UID 0, and UID 0 is root. Each user also has a primary group membership, reflected in their numeric group ID, or GID. In this case, root's GID is 0, which is the numeric group identifier for the group "wheel". Each user needs to be in a group. The only other truly important bits are a user's home directory and their login shell - the last two fields. Let's go ahead and enter a user.

First, we pick a username. For this example, I'll pick the username "newbie". Next is a trickier part - the UID. Generally, you want to start real users off kinda high - I start at UID 1000, and take the first one after that that's free. Now, of course, the master.passwd file isn't necessarily in order of UID. Here's a handy command to see what UIDs are taken:

awk -F : < /etc/passwd '{print $3}' | sort -n

On my system, UIDs 1000, 1001, and 1002 are taken, so for this example, I pick 1003. Now we know the user is "newbie" with UID 1003. Now we have to pick a GID. This is a no-brainer if you've added users before. Maybe you have a group called "user" or something like that, but more likely you wanna just give a user their own group. If this is the case, you can be neat and match UID to GID. In this case, I ask myself, is GID 1003 available?

awk -F : < /etc/group '{print $3}' | sort -n

In this case, it is, so I move onto the home directory. "/home/newbie" sounds like a good call, doesn't it? And a shell? Well, I like "/usr/local/bin/tcsh" although you could give your newbie any shell found in the file /etc/shells. We boil it down to this:

Username: newbie
UID: 1003
GID: 1003
Home: /home/newbie
Shell: /usr/local/bin/tcsh

This translates into the line:

newbie:*:1003:1003::0:0:N. E. Wbie:/home/newbie:/usr/local/bin/tcsh

Notice I filled in the "full name" field as well? Fill this in as you please, but bear in mind that colons are verbotten and commas have special meanings to the GECOS crowd, so you'll probably want to avoid both.

Go to the bottom of your file, and fill out the line you've formatted. Watch out for line wraps! When you like the entry you've added, save and exit the file. If all goes well, vipw will rebuild the databases for you and return you to your prompt. Otherwise it will complain and give you a chance to make amends before dropping your change entirely.

Now the cool thing is that vipw rebuilds the database for you. Even cooler is that it puts an exclusive lock on the master.passwd file while you edit the file and generate the new system database files, so nobody else can muck it up while you work. This is an important feature if you have more than one person who may be changing the master.passwd file. Remember, users can make changes to this file through the passwd program and the like.

Did you create a new group for your newbie? Go ahead and add him to your /etc/group file. It's not rocket science, here's what I did:

newbie:*:1003:

With the first two steps out of the way, we can make the user's home directory:

cd /home mkdir newbie chown -R newbie.newbie newbie

An explanation of that chown -R ... -R means "recursive" ... this is useful if you give poor old newbie some default .cshrc and the like. This will recurse through his directory and chown _all_ of newbie's files. The newbie.newbie means to change the owner to newbie, and the group to newbie as well. Still confused? RTFM!

The last step is to give newbie a password. With a password of *, newbie just can't log in. You can give newbie a password by typing "passwd newbie" at the prompt.

THE HARDER WAY: pwd_mkdb and adduser

If you ever needed to rebuild the system databases manually for some reason, you could run pwd_mkdb -p /etc/master.passwd. In general, you want to avoid running pwd_mkdb if you can, because there are race conditions which can and will surface if you've ever got more than one person running it. Try running adduser in more than one term at a time and you might discover these troubles for yourself. Try running vipw in more than one term and you'll see it complain.

THE ENLIGHTENED WAY: pw

Once upon a time in late 1996, FreeBSD adopted a program called pw. Pw is useful for adding, removing, and modifying users and groups alike. It is extremely powerful, flexible, and configurable, and it works just as happily if you run it concurrently with itself. As far as cool things that come with FreeBSD go, pw ranks up there with hiding the encrypted passwords.

For example, to do everything we did above, the root user could simply type:

pw useradd cluebie -c "Clue Bie" -d /home/cluebie -m -s /usr/local/bin/tcsh

The -m option means that pw will attempt to create cluebie's home directory. It will also copy some default config files into it. The other options are pretty straightforward, but you are encouraged to read the man page. By default, pw creates a new group for cluebie.

Okay well that's rather nifty, but isn't that an awful lot to remember for adding just one user? You bet! Let's do one better. Pw supports a configuration file. Let's set our defaults right now:

pw useradd -D -m -s /usr/local/bin/tcsh

Here, the -D says to create a configuration file, that will by default set the shell to tcsh, and instruct pw to create the user's home directory. What's even better is that you can go through the config file, read it's comments, and tweak it yourself. Use your editor on /etc/pw.conf.

Here are a few things I like to do:

defaultpasswd = "random"
This instructs pw to generate a new random password when a user is added. It spits out this incomprehensible string which I'll mail to my friend, who will promptly change it to something they have a prayer of remembering. This is a pretty secure way of setting things up.

shellpath = "/bin:/usr/local/bin"
This works pretty well - the default shells come in /bin, and the ones you add from ports end up in /usr/local/bin.

shells = "sh","csh","tcsh"
This lets you specify your available shells to pw without the whole path. Next time you have a csh friend to add, you can just pw useradd buddy -s csh.

defaultshell = "tcsh"
Set this to whatever your cabal of friends prefers to use. Some folks are down with bash and zsh, more power to you.

Another thing you might want to do now is to visit /usr/share/skel and look at customizing a few of those config files. Remember, don't get too freaky, these are the defaults everyone's going to get! But you might want to give them something to chew on. If you haven't guessed, the dot.filename stuff converts to .filename. Note also that the read, write and execute permissions are also preserved when pw copies them.

As I mentioned earlier, adduser is not so useful if you're in a larger organization and might be adding more than one user at any given time. Pw is more useful here, but not as cuddly for less experienced folks to work with. If anyone's interested, I'll include an article in next month's Dæmon News talking about writing a Perl script to interface with pw. I'd like as much feedback as I can get on this article though, please feel free to share any comments, criticisms or suggestions with dannyman@dannyland.org.

	User Management Copyright © 1999 Dannyman INTRODUCTION This article is written partly as a how-to, and partly as an explanation of a little more than the average FreeBSD user would want to know about the FreeBSD user management system. While it goes into more gory details than you might want to know, it is written with the new user in mind. If you want to savour every detail and come to grok user management system in all its glory, read this thing the whole way through, then read all the related man pages, and then delve into the code. If you just want to add users right away, skip down to the section on pw. I'm guessing most readers will be somewhere in the middle, and will browse through the first few parts with varying degrees of interest. GRITTY DETAILS If all you want to do is add users, then skip on to the next part. If you want to have a basic understanding of how the password system works, slog through here. The process of adding a user to a FreeBSD system comes in three steps: 1) Add an entry for user in /etc/master.passwd. 2) Update the system user databases. 3) Create a home directory for user. The master.passwd file is where user information and passwords are stored and maintained. This is a text file, and each line describes a user as a series of ten colon separated fields. This file is edited by programs like chfn and passwd to update user data, and by the system administrator when adding or removing users or making other changes. In order for FreeBSD to access information on users, the master.passwd file is copied into two system databases. This allows the system to access user information faster through a database than a text file, and it gives the administrator something to work on besides the "live" system. If an error is made when editing the master.passwd file, this error may be caught by pwd_mkdb, the program which generates the database files. Why two system databases, you might ask yourself? The master.passwd file contains encrypted passwords for each user. For this reason only root can read it. If anyone could read it, anyone could run a password-cracking program and have a decent hope of eventually guessing a few passwords, thus gaining access to other peoples' accounts. When the databases are built, two separate copies are made - one database has all the user information, except passwords, and is accessible by the whole system. The other is the "secure" database, which contains everything in the other database but with passwords as well. This database, like the master.passwd file, is readable only by root, and is used by programs like login to verify that a user's password is correct. Additionally, pwd_mkdb usually generates another file called, simply enough, passwd. This file is readable by everyone, and contains all the stuff found in master.passwd except for the passwords. The reason this file is created is because on some other Unix systems, this file has the role that master.passwd has on FreeBSD. Since some users and programs may expect to be able to read a file with user information called passwd, FreeBSD keeps the root-only version of passwd in a different place, and provides the traditional, readable passwd file, minus encrypted passwords, in its traditional spot. Confused yet? Here's a summary: /etc/master.passwd - user data and passwords, text, root only, "master" file /etc/spwd.db - user data and passwords, system database, root only /etc/pwd.db - user data, no passwords, public system database /etc/passwd - user data, no passwords, public text for compatability THE HARD WAY: vipw Alright, you want to add a user to the system. Let's review the three steps you probably skipped in PART I: 1) Add an entry for user in /etc/master.passwd. 2) Update the system user databases. 3) Create a home directory for user. You want to add a user the hard way? Go to your root prompt and enter the vipw command. Assuming you have set your `EDITOR` environment variable to something you're comfortable with, you should find yourself presented with several rows of user accounts, stored as a series of colon-separated fields. At this point you could either RTFM - `man 5 passwd`, or you could bear with my explanation here. Start at the top. You should see something like: `root:r3dbpPtFuaZlQ:0:0::0:0:Charlie &:/root:/bin/csh` Those fields, read in order: 1) username 2) encrypted password 3) Numeric User ID 4) Numeric Group ID 5) User's login class 6) Password's expiration time 7) Account's expiration time 8) User's "full name" 9) User's home directory 10) User's login shell The important bits you want to consider here are that username and numeric user ID, UID, should both be unique and tied directly to each other. In this case, root has UID 0, and UID 0 is root. Each user also has a primary group membership, reflected in their numeric group ID, or GID. In this case, root's GID is 0, which is the numeric group identifier for the group "wheel". Each user needs to be in a group. The only other truly important bits are a user's home directory and their login shell - the last two fields. Let's go ahead and enter a user. First, we pick a username. For this example, I'll pick the username "newbie". Next is a trickier part - the UID. Generally, you want to start real users off kinda high - I start at UID 1000, and take the first one after that that's free. Now, of course, the master.passwd file isn't necessarily in order of UID. Here's a handy command to see what UIDs are taken: `awk -F : < /etc/passwd '{print $3}' \| sort -n` On my system, UIDs 1000, 1001, and 1002 are taken, so for this example, I pick 1003. Now we know the user is "newbie" with UID 1003. Now we have to pick a GID. This is a no-brainer if you've added users before. Maybe you have a group called "user" or something like that, but more likely you wanna just give a user their own group. If this is the case, you can be neat and match UID to GID. In this case, I ask myself, is GID 1003 available? `awk -F : < /etc/group '{print $3}' \| sort -n` In this case, it is, so I move onto the home directory. "/home/newbie" sounds like a good call, doesn't it? And a shell? Well, I like "/usr/local/bin/tcsh" although you could give your newbie any shell found in the file /etc/shells. We boil it down to this: Username: newbie UID: 1003 GID: 1003 Home: /home/newbie Shell: /usr/local/bin/tcsh This translates into the line: `newbie::1003:1003::0:0:N. E. Wbie:/home/newbie:/usr/local/bin/tcsh` Notice I filled in the "full name" field as well? Fill this in as you please, but bear in mind that colons are verbotten and commas have special meanings to the GECOS crowd, so you'll probably want to avoid both. Go to the bottom of your file, and fill out the line you've formatted. Watch out for line wraps! When you like the entry you've added, save and exit the file. If all goes well, vipw will rebuild the databases for you and return you to your prompt. Otherwise it will complain and give you a chance to make amends before dropping your change entirely. Now the cool thing is that vipw rebuilds the database for you. Even cooler is that it puts an exclusive lock on the master.passwd file while you edit the file and generate the new system database files, so nobody else can muck it up while you work. This is an important feature if you have more than one person who may be changing the master.passwd file. Remember, users can make changes to this file through the passwd program and the like. Did you create a new group for your newbie? Go ahead and add him to your /etc/group file. It's not rocket science, here's what I did: `newbie::1003:` With the first two steps out of the way, we can make the user's home directory: `cd /home mkdir newbie chown -R newbie.newbie newbie` An explanation of that chown -R ... -R means "recursive" ... this is useful if you give poor old newbie some default .cshrc and the like. This will recurse through his directory and chown _all_ of newbie's files. The newbie.newbie means to change the owner to newbie, and the group to newbie as well. Still confused? RTFM! The last step is to give newbie a password. With a password of *, newbie just can't log in. You can give newbie a password by typing "passwd newbie" at the prompt. THE HARDER WAY: pwd_mkdb and adduser If you ever needed to rebuild the system databases manually for some reason, you could run `pwd_mkdb -p /etc/master.passwd`. In general, you want to avoid running pwd_mkdb if you can, because there are race conditions which can and will surface if you've ever got more than one person running it. Try running adduser in more than one term at a time and you might discover these troubles for yourself. Try running vipw in more than one term and you'll see it complain. THE ENLIGHTENED WAY: pw Once upon a time in late 1996, FreeBSD adopted a program called pw. Pw is useful for adding, removing, and modifying users and groups alike. It is extremely powerful, flexible, and configurable, and it works just as happily if you run it concurrently with itself. As far as cool things that come with FreeBSD go, pw ranks up there with hiding the encrypted passwords. For example, to do everything we did above, the root user could simply type: `pw useradd cluebie -c "Clue Bie" -d /home/cluebie -m -s /usr/local/bin/tcsh` The -m option means that pw will attempt to create cluebie's home directory. It will also copy some default config files into it. The other options are pretty straightforward, but you are encouraged to read the man page. By default, pw creates a new group for cluebie. Okay well that's rather nifty, but isn't that an awful lot to remember for adding just one user? You bet! Let's do one better. Pw supports a configuration file. Let's set our defaults right now: `pw useradd -D -m -s /usr/local/bin/tcsh` Here, the -D says to create a configuration file, that will by default set the shell to tcsh, and instruct pw to create the user's home directory. What's even better is that you can go through the config file, read it's comments, and tweak it yourself. Use your editor on /etc/pw.conf. Here are a few things I like to do: defaultpasswd = "random" This instructs pw to generate a new random password when a user is added. It spits out this incomprehensible string which I'll mail to my friend, who will promptly change it to something they have a prayer of remembering. This is a pretty secure way of setting things up. shellpath = "/bin:/usr/local/bin" This works pretty well - the default shells come in /bin, and the ones you add from ports end up in /usr/local/bin. shells = "sh","csh","tcsh" This lets you specify your available shells to pw without the whole path. Next time you have a csh friend to add, you can just pw useradd buddy -s csh. defaultshell = "tcsh" Set this to whatever your cabal of friends prefers to use. Some folks are down with bash and zsh, more power to you. Another thing you might want to do now is to visit /usr/share/skel and look at customizing a few of those config files. Remember, don't get too freaky, these are the defaults everyone's going to get! But you might want to give them something to chew on. If you haven't guessed, the dot.filename stuff converts to .filename. Note also that the read, write and execute permissions are also preserved when pw copies them. As I mentioned earlier, adduser is not so useful if you're in a larger organization and might be adding more than one user at any given time. Pw is more useful here, but not as cuddly for less experienced folks to work with. If anyone's interested, I'll include an article in next month's Dæmon News talking about writing a Perl script to interface with pw. I'd like as much feedback as I can get on this article though, please feel free to share any comments, criticisms or suggestions with dannyman@dannyland.org. Dannyman, dannyman@dannyland.org