Managing User Accounts

Developer Resources
PDF Documents
Caution: This version of this document is no longer maintained. For the latest documentation, see

Managing User Accounts

This chapter includes:

This chapter explains how user accounts work, how users can change their password by using the passwd utility, and how system administrators can use the passwd utility and edit account database files to create and maintain users' accounts.

Note: In embedded systems, the designer may choose to eliminate the account-related files from the system, disabling logins and references to users and groups by name, even though the system remains fully multiuser and may have multiple numeric user IDs running programs and owning system resources. If your system is configured this way, most of this chapter won't be relevant to you.

What does a user account do?

A user account associates a textual user name with a numeric user ID and group ID, a login password, a user's full name, a home directory, and a login shell. This data is stored in the /etc/passwd and /etc/shadow files, where it's accessed by login utilities as well as by other applications that need user-account information.

Note: User names and passwords are case-sensitive.

User accounts let:

Groups are used to convey similar permissions to groups of users on the system. Entries in /etc/passwd and /etc/group define group membership, while the group ID of a running program and the group ownership and permission settings of individual files and directories determine the file permission granted to a group member.

When you log in, you're in the group specified in /etc/passwd. You can switch to another of your groups by using the newgrp utility.

User accounts vs user IDs: login, lookup, and permissions

Once you've logged in, the numeric user ID of your running programs and system resources determines your programs' ability to access resources and perform operations, such as sending signals to other processes. Textual names are used only by utilities and applications that need to convert between names and numeric IDs.

Note: Changing user names, groups, user IDs, and so on in the account database has no effect on your permission to access files, etc. until you next log in.

The root user (user ID 0) has permission to do nearly anything to files, regardless of their ownership and permission settings. For more information, see File ownership and permissions in Working with Files.

Note: When the shell interprets a ~username pathname, it gets the user's home directory from /etc/passwd. If you remove or change a user's account, any shell running in the system that had previously accessed that user's home directory via ~username may be using the old home directory information to determine the actual path, because the shell caches the data.

New shells read the data afresh from /etc/passwd. This may be a problem if a shell script that uses ~username invokes another shell script that also uses this feature: the two scripts would operate on different paths if the home directory information associated with the user name has changed since the first shell looked the information up.

What happens when you log in?

You typically start a session on the computer by logging in (see Logging In, Logging Out, and Shutting Down); the configuration of your account determines what happens then.

When you log in, the system creates a user session led by a process that runs under your user ID and default group ID, as determined from your account entry in /etc/passwd.

The user ID and group ID determine the permission the process has to access files and system resources. In addition, if the process creates any files and directories, they belong to that user and group. Each new process that you start inherits your user ID and group ID from its parent process. For more information about file permissions, see File ownership and permissions in Working with Files.

Note: For more information on characteristics that programs inherit from their parent programs, see spawn() in the Neutrino Library Reference. For more information on sessions and process groups, see IEEE Std 1003.1-2001 Standard for Information Technology Portable Operating System Interface.

The text-mode login (login) handles a user's login shell differently from the graphical login (phlogin2 or phlogin):

Account database

The account database consists of the following files (listed with the appropriate access permissions):

File: Owner: Group: Permissions:
/etc/passwd root root rw- r-- r--
/etc/group root root rw- r-- r--
/etc/shadow root root rw- --- ---
/etc/.pwlock root root rw- r-- r--

Note that anyone can read /etc/passwd. This lets standard utilities find information about users. The encrypted password isn't stored in this file; it's stored in /etc/shadow, which only root has permission to read. This helps prevent attempts to decrypt the passwords.

Note: To protect the security of your user community, make sure you don't change these permissions.


Each line in /etc/passwd is in this format:


The fields are separated by colons and include:

The user's login name. This can contain any characters except a colon (:), but you should probably avoid any of the shell's special characters. For more information, see Quoting special characters in Using the Command Line.
This field must be empty or x. If empty, the user has no password; if x, the user's encrypted password is in /etc/shadow.
The numeric user ID.
The numeric group ID.
A free-form comment field that usually contains at least the user's real name; this field must not contain a colon.
The user's home directory.
The initial command to start after login. The default is /bin/sh.

Note: You can't specify any arguments to the login program.

Here's an sample entry from /etc/passwd:

fred:x:290:120:Fred L. Jones:/home/fred:/bin/sh


Each line in /etc/group is in this format:


The fields are separated by colons and include:

The name of the group. Like a user's name, this can contain any characters except a colon (:), but you should probably avoid any of the shell's special characters. For more information, see Quoting special characters in Using the Command Line.
The password for the group. Neutrino doesn't support group passwords.
The numeric group ID.
The user names of the accounts that belong to this group, separated by commas (,).

Here's a sample entry:



Each line in /etc/shadow is in this format:


The fields are separated by colons and include:

The user's login name.
The user's encrypted password.


The passwd utility creates /etc/.pwlock to indicate to other instances of passwd that the password file is currently being modified. When passwd finishes, it removes the lock file.

If you're the system administrator, and you need to edit the account files, you should:

  1. Lock the password database: if the /etc/.pwlock file doesn't exist, lock the account files by creating it; if it does exist, wait until it's gone.
  2. Open the appropriate file or files, using the text editor of your choice, and make the necessary changes.
  3. Unlock the password database by removing /etc/.pwlock.

Managing your own account

As a regular (non-root) user, you can change your own password. You can also customize your environment by modifying the configuration files in your home directory; see Configuring Your Environment.

Changing your password

To change your password, use the passwd utility; if you're using Photon, you can use phuser. Either utility prompts you for your current password and then for a new one. You have to repeat the new password to guard against typographical errors. In phuser, you can also choose an icon to represent yourself when you log in.

Depending on the password rules that the system administrator has set, passwd may require that you enter a password of a certain length or one that contains certain elements (such as a combination of letters, numbers, and punctuation). If the password you select doesn't meet the criteria, passwd asks you to choose another.

If other users can access your system (e.g. it's connected to the Internet, has a dial-in modem, or is physically accessible by others), be sure to choose a password that will secure your account from unauthorized use. You should choose passwords that:

For more information on system security, see Securing Your System.

Forgot your password?

If you forget your password, ask the system administrator (root user) to assign a new password to your account. Only root can do this.

In general, no one can retrieve your old password from the /etc/shadow file. If your password is short or a single word, your system administrator — or a hacker — can easily figure it out, but you're better off with a new password.

If you're the system administrator, and you've forgotten the password for root, you need to find an alternate way to access the /etc/passwd and /etc/shadow files in order to reset the root password. Some possible ways to do this are:

Managing other accounts

As a system administrator, you need to add and remove user accounts and groups, manage passwords, and troubleshoot users' problems. You must be logged in as root to do this, because other users don't have permission to modify /etc/passwd, /etc/shadow, and /etc/group.

Caution: While it's safe at any time to use the passwd utility to change the password of an existing user who already has a password, it isn't necessarily safe to make any other change to the account database while your system is in active use. Specifically, the following operations may cause applications and utilities to operate incorrectly when handling user-account information:
  • adding a user, either by using the passwd utility or by manually editing /etc/passwd
  • putting a password on an account that previously didn't have a password
  • editing the /etc/passwd or /etc/group files

If it's likely that someone might try to use the passwd utility or update the account database files while you're editing them, lock the password database by creating the /etc/.pwlock file before making your changes.

As described below, you should use the passwd utility to change an account's password. However, you need to use a text editor to:

If you're using Photon, you can use phuser, which provides a graphical front end to passwd and also lets you choose an icon or shell for a user and edit the groups.

Note: The changes you make manually to the account files aren't checked for conformance to the rules set in the passwd configuration file. For more information, see the description of /etc/default/passwd in the documentation for passwd in the Utilities Reference.

Adding users

To add a user:
  1. Log in as root.
  2. Either use phuser if you're using Photon, or use passwd:
    passwd new_username

    Note: Make sure that the user name is no longer than 14 characters; otherwise, that user won't be able to log in.

If you specify a user name that's already registered, passwd assumes you want to change their password. If that's what you want, just type in the new password and then confirm it. If you don't wish to change the user's password, type Ctrl-C to terminate the passwd utility without changing anything.

If the user name isn't already registered, passwd prompts you for account information, such as the user's group list, home directory, and login shell. The /etc/default/passwd configuration file specifies the rules that determine the defaults for new accounts. For more information, see the description of this file in the documentation for passwd.

The prompts include:

User id # (default)
Specify the numeric user ID for the new user. By default, no two users may share a common user ID, because applications won't be able to determine the user name that corresponds to that user ID.
Group id # (default)
Choose a numeric group ID that the user will belong to after initially logging in.

Note: The passwd utility doesn't add the new user to the group's entry in the /etc/group file; you need to do that manually using a text editor. See Defining Groups for more details.

Real name ()
Enter the user's real name. The real name isn't widely used by system utilities, but may be used by applications such as email.
Home directory (/home/username)
Enter the pathname of the user's home directory, usually /home/username. The passwd utility automatically creates the directory you specify. If the directory already exists, passwd by default prompts you to select a different pathname. For information on disabling this feature, see the description of /etc/default/passwd in the documentation for passwd.
Login shell (/bin/sh)
This is the program that's run once the user logs in. Traditionally, this is the shell (/bin/sh), giving the user an interactive command line upon logging in.

Note: You can specify any program as the login shell, but you can't pass command-line arguments to it. Also, the phlogin2 or phlogin graphical login fails if the login shell is anything but a POSIX-compatible shell.

Instead of specifying a custom program within the account entry, you should customize the user's .profile file in their home directory; /bin/sh runs this profile automatically when it starts up. For more information, see Configuring Your Environment.

New password:
Specify the initial password for the account. You're asked to confirm it by typing it again.

Removing accounts

To remove a user account:
  1. Lock the user account database: if the /etc/.pwlock file doesn't exist, lock the account files by creating it; if it does exist, wait until it's gone.
  2. Remove the account entry in /etc/passwd and /etc/shadow to disable future logins, or change the login shell to a program that simply terminates, or that displays a message and then terminates.
  3. Remove references to the user from the /etc/group file.
  4. Unlock the account database by removing /etc/.pwlock.
  5. If necessary, remove or change ownership of system resources that the user owned.
  6. If necessary, remove or alter references to the user in email systems, TCP/IP access control files, applications, and so on.

Instead of removing a user, you can disable the account by using the passwd utility to change the account's password. In this way, you can tell which system resources the former user owned, since the user ID-to-name translation still works. When you do this, the passwd utility automatically handles the necessary locking and unlocking of the account database.

If you ever need to log into that account, you can either use the su (“switch user”) utility to switch to that account (from root), or log in to the account. If you forget the password for the account, remember that the root user can always change it.

What should you do with any resources that a former user owned? Here are some of your options:

Caution: If you remove a user's account in the account database but don't remove or change the ownership of their files, it's possible that a future account may end up with the same numeric user ID, which would make the new user the owner of any files left behind by the old one.

Defining groups

A user's account entry in /etc/passwd solely determines which group the user is part of on logging in, while the groups a user is named in within the /etc/group file solely determine the groups the user may switch to after logging in (see the newgrp utility). As with user names and IDs, the numeric effective group ID of a running program determines its access to resources.

For example, if you have a team of people that require access to /home/projects on the system, but you don't want the other users to have access to it, do the following:

  1. Add a group called projects to the /etc/group file, adding all necessary users to that group (for details, see Creating a new group,” below).
  2. If you want this group to be the default for these users, change their account entries in /etc/passwd to reflect their new default group ID.
  3. Recursively change the group ownership and permissions on /home/projects:
    chgrp -R projects /home/projects
    chmod -R g+rw /home/projects
  4. Remove access for all other users:
    chmod -R o-rwx /home/projects

For more details on permissions, see File ownership and permissions in Working with Files.

Creating a new group

To create a new group:
Open /etc/group in a text editor, then add a line that specifies the new group's name, ID, and members. For example:

For more information about the fields, see /etc/group,” earlier in this chapter.

Caution: Do this work at a time when the system is idle. As your text editor writes the /etc/group file back, any application or utility that's trying to simultaneously read the /etc/group file (e.g. ls -l, newgrp) might not function correctly.

Modifying an existing group

Each time you add a new user to a group (e.g. when you use passwd to create a new user account), you need to edit the /etc/group file and add the user to the appropriate group entry. For instance, if you have an existing group techies and want to add zeke to the group, change:




You should do this at a time when you're certain no users or programs are trying to use the /etc/group file.


Here are some problems you might encounter while working with passwords and user accounts:

The passwd utility seems to hang after I change my password.
The passwd utility uses the /etc/.pwlock file as a lock while updating the password database. If the file already exists, passwd won't run.

If the system crashes during the update, and /etc/.pwlock still exists, passwd refuses to work until the system administrator removes the file.

If the password files are left in an inconsistent state as a result of the crash, the system administrator should also copy the backup files, /etc/oshadow and /etc/opasswd, to /etc/shadow and /etc/passwd to prevent additional problems.

Why can't I log in in graphical mode?
If you enter your user name and password to the graphical login utility (phlogin2 or phlogin), and it silently returns you to the blank login form, then:
  • Your user name and password don't match an account in the system (user names and passwords are both case-sensitive).


  • Your account has a login shell that isn't a standard POSIX shell.

In either case, see your system administrator for help.

Why can't I log in in text mode?
If you enter your user name and password to the text mode login prompt, login, and it responds Login incorrect, it's likely because your user name doesn't exist, or you've typed the wrong password. Both user names and passwords are case-sensitive; make sure you don't have Caps Lock on.

To avoid giving clues to unauthorized users, login doesn't tell you whether it's the user name or the password that's wrong. If you can't resolve the problem yourself, your system administrator (root user) can set a new password on your account.

This symptom can also occur if one or more password-related files are missing. If the system administrator is in the middle of updating the files, it's possible that its absence will be temporary. Try again in a minute or two if this might be the case. Otherwise, see your system administrator for help.

If you are the system administrator and can't access the system, try accessing it from another Neutrino machine using Qnet, from a development machine using the qconn interface, or boot and run from the installation CD-ROM to gain shell access to examine and repair the necessary files.

My text-mode login fails with a message: command: No such file or directory.
The system couldn't find the command specified as your login shell. This might happen because:
  • The command wasn't found in login's PATH (usually /bin:/usr/bin). Specify the full pathname to the program (e.g. /usr/local/bin/myprogram) in the user's /etc/passwd account entry.
  • The account entry specifies options or arguments for your login shell. You can't pass arguments to the initial command, because the entire string is interpreted as the filename to be executed.