path: root/en_US.ISO8859-1/books/handbook/users/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="users">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Neil</firstname>
	<surname>Blakey-Milner</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>
    <!-- Feb 2000 -->
  </chapterinfo>

  <title>Users and Basic Account Management</title>

  <sect1 id="users-synopsis">
    <title>Synopsis</title>

    <para>&os; allows multiple users to use the computer at the same
      time.  While only one user can sit in front of the screen and
      use the keyboard at any one time, any number of users can log
      in to the system through the network.  To use the system, every
      user must have a user account.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>The differences between the various user accounts on a
	  &os; system.</para>
      </listitem>

      <listitem>
	<para>How to add and remove user accounts.</para>
      </listitem>

      <listitem>
	<para>How to change account details, such as the user's full
	  name or preferred shell.</para>
      </listitem>

      <listitem>
	<para>How to set limits on a per-account basis to control the
	  resources, such as memory and CPU time, that accounts and
	  groups of accounts are allowed to access.</para>
      </listitem>

      <listitem>
	<para>How to use groups to make account management
	  easier.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Understand the <link linkend="basics">basics of &unix;
	    and &os;</link>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="users-introduction">
    <title>Introduction</title>

    <para>Since all access to the &os; system is achieved via accounts
      and all processes are run by users, user and account management
      is important.</para>

    <para>Every account on a &os; system has certain information
      associated with it to identify the account.</para>

    <variablelist>
      <varlistentry>
	<term>User name</term>

	<listitem>
	  <para>The user name is typed at the <prompt>login:</prompt>
	    prompt.  User names must be unique on the system as no two
	    users can have the same user name.  There are a number of
	    rules for creating valid user names, documented in
	    &man.passwd.5;.  Typically user names consist of eight or
	    fewer all lower case characters in order to maintain
	    backwards compatibility with applications.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Password</term>

	<listitem>
	  <para>Each account has an associated password.  While the
	    password can be blank, this is highly discouraged and
	    every account should have a password.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>User ID (<acronym>UID</acronym>)</term>

	<listitem>
	  <para>The User ID (<acronym>UID</acronym>) is a number,
	    traditionally from 0 to 65535<footnote
	      id="users-largeuidgid">
	      <para>It is possible to use
		<acronym>UID</acronym>s/<acronym>GID</acronym>s as
		large as 4294967295, but such IDs can cause serious
		problems with software that makes assumptions about
		the values of IDs.</para>
	      </footnote>, used to uniquely identify the user to the
	    system.  Internally, &os; uses the
	    <acronym>UID</acronym> to identify users.  Commands that
	    allow a user name to be specified will first convert it to
	    the <acronym>UID</acronym>.  Though unlikely, it is
	    possible for several accounts with different user names to
	    share the same <acronym>UID</acronym>.  As far as &os; is
	    concerned, these accounts are one user.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Group ID (<acronym>GID</acronym>)</term>

	<listitem>
	  <para>The Group ID (<acronym>GID</acronym>) is a number,
	    traditionally from 0 to 65535<footnoteref
	      linkend="users-largeuidgid"/>, used to uniquely identify
	    the primary group that the user belongs to.  Groups are a
	    mechanism for controlling access to resources based on a
	    user's <acronym>GID</acronym> rather than their
	    <acronym>UID</acronym>.  This can significantly reduce the
	    size of some configuration files.  A user may also be a
	    member of more than one group.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Login class</term>

	<listitem>
	  <para>Login classes are an extension to the group mechanism
	    that provide additional flexibility when tailoring the
	    system to different users.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Password change time</term>

	<listitem>
	  <para>By default &os; does not force users to change their
	    passwords periodically.  Password expiration can be
	    enforced on a per-user basis, forcing some or all users to
	    change their passwords after a certain amount of time has
	    elapsed.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Account expiry time</term>

	<listitem>
	  <para>By default &os; does not expire accounts.  When
	    creating accounts that need a limited lifespan, such as
	    student accounts in a school, specify the account expiry
	    date.  After the expiry time has elapsed, the account
	    cannot be used to log in to the system, although the
	    account's directories and files will remain.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>User's full name</term>

	<listitem>
	  <para>The user name uniquely identifies the account to &os;,
	    but does not necessarily reflect the user's real name.
	    This information can be associated with the
	    account.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Home directory</term>

	<listitem>
	  <para>The home directory is the full path to a directory on
	    the system.  This is the user's starting directory when
	    the user logs in.  A common convention is to put all user
	    home directories under <filename
	      class="directory">/home/<replaceable>username</replaceable></filename>
	    or <filename
	      class="directory">/usr/home/<replaceable>username</replaceable></filename>.
	    Each user stores their personal files and subdirectories
	    in their own home directory.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>User shell</term>

	<listitem>
	  <para>The shell provides the default environment users use
	    to interact with the system.  There are many different
	    kinds of shells, and experienced users will have their own
	    preferences, which can be reflected in their account
	    settings.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>There are three main types of accounts: the <link
	linkend="users-superuser">superuser</link>, <link
	linkend="users-system">system accounts</link>, and <link
	linkend="users-user">user accounts</link>.  The superuser
      account, usually called <username>root</username>, is used to
      manage the system with no limitations on privileges.  System
      accounts are used to run services.  User accounts are
      assigned to real people and are used to log in and use the
      system.</para>

    <sect2 id="users-superuser">
      <title>The Superuser Account</title>

      <indexterm>
	<primary>accounts</primary>
	<secondary>superuser (root)</secondary>
      </indexterm>
      <para>The superuser account, usually called
	<username>root</username>, is used to perform system
	administration tasks and should not be used for day-to-day
	tasks like sending and receiving mail, general exploration of
	the system, or programming.</para>

      <para>This is because the superuser, unlike normal user
	accounts, can operate without limits, and misuse of the
	superuser account may result in spectacular disasters.  User
	accounts are unable to destroy the system by mistake, so it is
	generally best to use normal user accounts whenever possible,
	unless extra privilege is required.</para>

      <para>Always double and triple-check any commands issued as the
	superuser, since an extra space or missing character can mean
	irreparable data loss.</para>

      <para>Always create a user account for the system administrator
	and use this account to log in to the system for general
	usage.  This applies equally to multi-user or single-user
	systems.  Later sections will discuss how to create additional
	accounts and how to change between the normal user and
	superuser.</para>
    </sect2>

    <sect2 id="users-system">
      <title>System Accounts</title>

      <indexterm>
	<primary>accounts</primary>
	<secondary>system</secondary>
      </indexterm>
      <para>System accounts are used to run services such as DNS,
	mail, and web servers.  The reason for this is security; if
	all services ran as the superuser, they could act without
	restriction.</para>

      <indexterm>
	<primary>accounts</primary>
	<secondary><username>daemon</username></secondary>
      </indexterm>
      <indexterm>
	<primary>accounts</primary>
	<secondary><username>operator</username></secondary>
      </indexterm>
      <para>Examples of system accounts are
	<username>daemon</username>, <username>operator</username>,
	<username>bind</username>, <username>news</username>, and
	<username>www</username>.</para>

      <indexterm>
	<primary>accounts</primary>
	<secondary><username>nobody</username></secondary>
      </indexterm>
      <para><username>nobody</username> is the generic unprivileged
	system account.  However, the more services that use
	<username>nobody</username>, the more files and processes that
	user will become associated with, and hence the more
	privileged that user becomes.</para>
    </sect2>

    <sect2 id="users-user">
      <title>User Accounts</title>

      <indexterm>
	<primary>accounts</primary>
	<secondary>user</secondary>
      </indexterm>
      <para>User accounts are the primary means of access for real
	people to the system.  User accounts insulate the user and
	the environment, preventing users from damaging the system
	or other users, and allowing users to customize their
	environment without affecting others.</para>

      <para>Every person accessing the system should have a unique
	user account.  This allows the administrator to find out who
	is doing what, prevents users from clobbering each others'
	settings or reading each others' mail, and so forth.</para>

      <para>Each user can set up their own environment to accommodate
	their use of the system, by using alternate shells, editors,
	key bindings, and language.</para>
    </sect2>
  </sect1>

  <sect1 id="users-modifying">
    <title>Modifying Accounts</title>

    <indexterm>
      <primary>accounts</primary>
      <secondary>modifying</secondary>
    </indexterm>

    <para>&os; provides a variety of different commands to manage
      user accounts.  The most common commands are summarized below,
      followed by more detailed examples of their usage.</para>

    <informaltable frame="none" pgwide="1">
      <tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>

	<thead>
	  <row>
	    <entry>Command</entry>
	    <entry>Summary</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>&man.adduser.8;</entry>
	    <entry>The recommended command-line application for adding
	      new users.</entry>
	  </row>

	  <row>
	    <entry>&man.rmuser.8;</entry>
	    <entry>The recommended command-line application for
	      removing users.</entry>
	  </row>

	  <row>
	    <entry>&man.chpass.1;</entry>
	    <entry>A flexible tool for changing user database
	      information.</entry>
	  </row>

	  <row>
	    <entry>&man.passwd.1;</entry>
	    <entry>The simple command-line tool to change user
	      passwords.</entry>
	  </row>

	  <row>
	    <entry>&man.pw.8;</entry>
	    <entry>A powerful and flexible tool for modifying all
	      aspects of user accounts.</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <sect2 id="users-adduser">
      <title><command>adduser</command></title>

      <indexterm>
	<primary>accounts</primary>
	<secondary>adding</secondary>
      </indexterm>
      <indexterm>
	<primary><command>adduser</command></primary>
      </indexterm>
      <indexterm>
	<primary><filename
	  class="directory">/usr/share/skel</filename></primary>
      </indexterm>
      <indexterm><primary>skeleton directory</primary></indexterm>
      <para>&man.adduser.8; is a simple program for adding new users
	When a new user is added, this program automatically updates
	<filename>/etc/passwd</filename> and
	<filename>/etc/group</filename>.  It also creates a home
	directory for the new user, copies in the default
	configuration files from <filename
	  class="directory">/usr/share/skel</filename>, and can
	optionally mail the new user a welcome message.</para>

      <example>
	<title>Adding a User on &os;</title>

	<screen>&prompt.root; <userinput>adduser</userinput>
Username: <userinput>jru</userinput>
Full name: <userinput>J. Random User</userinput>
Uid (Leave empty for default):
Login group [jru]:
Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput>
Login class [default]:
Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput>
Home directory [/home/jru]:
Home directory permissions (Leave empty for default):
Use password-based authentication? [yes]:
Use an empty password? (yes/no) [no]:
Use a random password? (yes/no) [no]:
Enter password:
Enter password again:
Lock out the account after creation? [no]:
Username   : jru
Password   : ****
Full Name  : J. Random User
Uid        : 1001
Class      :
Groups     : jru wheel
Home       : /home/jru
Shell      : /usr/local/bin/zsh
Locked     : no
OK? (yes/no): <userinput>yes</userinput>
adduser: INFO: Successfully added (jru) to the user database.
Add another user? (yes/no): <userinput>no</userinput>
Goodbye!
&prompt.root;</screen>
      </example>

      <note>
	<para>Since the password is not echoed when typed, be careful
	  to not mistype the password when creating the user
	  account.</para>
      </note>
    </sect2>

    <sect2 id="users-rmuser">
      <title><command>rmuser</command></title>

      <indexterm><primary><command>rmuser</command></primary></indexterm>
      <indexterm>
	<primary>accounts</primary>
	<secondary>removing</secondary>
      </indexterm>

      <para>To completely remove a user from the system use
	&man.rmuser.8;.  This command performs the following
	steps:</para>

      <procedure>
	<step>
	  <para>Removes the user's &man.crontab.1; entry if one
	    exists.</para>
	</step>

	<step>
	  <para>Removes any &man.at.1; jobs belonging to the
	    user.</para>
	</step>

	<step>
	  <para>Kills all processes owned by the user.</para>
	</step>

	<step>
	  <para>Removes the user from the system's local password
	    file.</para>
	</step>

	<step>
	  <para>Removes the user's home directory, if it is owned by
	    the user.</para>
	</step>

	<step>
	  <para>Removes the incoming mail files belonging to the user
	    from <filename
	      class="directory">/var/mail</filename>.</para>
	</step>

	<step>
	  <para>Removes all files owned by the user from temporary
	    file storage areas such as <filename
	      class="directory">/tmp</filename>.</para>
	</step>

	<step>
	  <para>Finally, removes the username from all groups to which
	    it belongs in <filename>/etc/group</filename>.</para>

	  <note>
	    <para>If a group becomes empty and the group name is the
	      same as the username, the group is removed.  This
	      complements the per-user unique groups created by
	      &man.adduser.8;.</para>
	  </note>
	</step>
      </procedure>

      <para>&man.rmuser.8; cannot be used to remove superuser
	accounts since that is almost always an indication of massive
	destruction.</para>

      <para>By default, an interactive mode is used, as shown
	in the following example.</para>

      <example>
	<title><command>rmuser</command> Interactive Account
	  Removal</title>

	<screen>&prompt.root; <userinput>rmuser jru</userinput>
Matching password entry:
jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
Is this the entry you wish to remove? <userinput>y</userinput>
Remove user's home directory (/home/jru)? <userinput>y</userinput>
Updating password file, updating databases, done.
Updating group file: trusted (removing group jru -- personal group is empty) done.
Removing user's incoming mail file /var/mail/jru: done.
Removing files belonging to jru from /tmp: done.
Removing files belonging to jru from /var/tmp: done.
Removing files belonging to jru from /var/tmp/vi.recover: done.
&prompt.root;</screen>
      </example>
    </sect2>

    <sect2 id="users-chpass">
      <title><command>chpass</command></title>

      <indexterm><primary><command>chpass</command></primary></indexterm>
      <para>&man.chpass.1; can be used to change user database
	information such as passwords, shells, and personal
	information.</para>

      <para>Only the superuser can change other users' information and
	passwords with &man.chpass.1;.</para>

      <para>When passed no options, aside from an optional username,
	&man.chpass.1; displays an editor containing user information.
	When the user exists from the editor, the user database is
	updated with the new information.</para>

      <note>
	<para>You will be asked for your password after exiting the
	  editor if you are not the superuser.</para>
      </note>

      <example>
	<title>Interactive <command>chpass</command> by
	  Superuser</title>

	<screen>#Changing user database information for jru.
Login: jru
Password: *
Uid [#]: 1001
Gid [# or name]: 1001
Change [month day year]:
Expire [month day year]:
Class:
Home directory: /home/jru
Shell: /usr/local/bin/zsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:</screen>
      </example>

      <para>A user can change only a small subset of this
	information, and only for their own user account.</para>

      <example>
	<title>Interactive <command>chpass</command> by Normal
	  User</title>

	<screen>#Changing user database information for jru.
Shell: /usr/local/bin/zsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:</screen>
      </example>

      <note>
	<para>&man.chfn.1; and &man.chsh.1; are links to
	  &man.chpass.1;, as are &man.ypchpass.1;, &man.ypchfn.1;, and
	  &man.ypchsh.1;.  <acronym>NIS</acronym> support is
	  automatic, so specifying the <literal>yp</literal> before
	  the command is not necessary.  How to configure NIS is
	  covered in <link linkend="network-servers"></link>.</para>
      </note>
    </sect2>
    <sect2 id="users-passwd">
      <title><command>passwd</command></title>

      <indexterm><primary><command>passwd</command></primary></indexterm>
      <indexterm>
	<primary>accounts</primary>
	<secondary>changing password</secondary>
      </indexterm>
      <para>&man.passwd.1; is the usual way to change your own
	password as a user, or another user's password as the
	superuser.</para>

      <note>
	<para>To prevent accidental or unauthorized changes, the user
	  must enter their original password before a new password can
	  be set.  This is not the case when the superuser changes a
	  user's password.</para>
      </note>

      <example>
	<title>Changing Your Password</title>

	<screen>&prompt.user; <userinput>passwd</userinput>
Changing local password for jru.
Old password:
New password:
Retype new password:
passwd: updating the database...
passwd: done</screen>
      </example>

      <example>
	<title>Changing Another User's Password as the
	  Superuser</title>

        <screen>&prompt.root; <userinput>passwd jru</userinput>
Changing local password for jru.
New password:
Retype new password:
passwd: updating the database...
passwd: done</screen>
      </example>

      <note>
	<para>As with &man.chpass.1;, &man.yppasswd.1; is a link to
	  &man.passwd.1;, so NIS works with either command.</para>
      </note>
    </sect2>


    <sect2 id="users-pw">
      <title><command>pw</command></title>

      <indexterm><primary><command>pw</command></primary></indexterm>

      <para>&man.pw.8; is a command line utility to create, remove,
	modify, and display users and groups.  It functions as a front
	end to the system user and group files.  &man.pw.8; has a very
	powerful set of command line options that make it suitable for
	use in shell scripts, but new users may find it more
	complicated than the other commands presented in this
	section.</para>
    </sect2>


  </sect1>

  <sect1 id="users-limiting">
    <title>Limiting Users</title>

    <indexterm><primary>limiting users</primary></indexterm>
    <indexterm>
      <primary>accounts</primary>
      <secondary>limiting</secondary>
    </indexterm>
    <para>&os; provides several methods for an administrator to limit
      the amount of system resources an individual may use.  These
      limits are discussed in two sections: disk quotas and other
      resource limits.</para>

    <indexterm><primary>quotas</primary></indexterm>
    <indexterm>
      <primary>limiting users</primary>
      <secondary>quotas</secondary>
    </indexterm>
    <indexterm><primary>disk quotas</primary></indexterm>
    <para>Disk quotas limit the amount of disk space available to
      users and provide a way to quickly check that usage without
      calculating it every time.  Quotas are discussed in <link
	linkend="quotas"></link>.</para>

    <para>The other resource limits include ways to limit the amount
      of CPU, memory, and other resources a user may consume.  These
      are defined using login classes and are discussed here.</para>

    <indexterm>
      <primary><filename>/etc/login.conf</filename></primary>
    </indexterm>
    <para>Login classes are defined in
      <filename>/etc/login.conf</filename> and are described in detail
      in &man.login.conf.5;.  Each user account is assigned to a login
      class, <literal>default</literal> by default, and each login
      class has a set of login capabilities associated with it.  A
      login capability is a
      <literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal>
      pair, where <replaceable>name</replaceable> is a well-known
      identifier and <replaceable>value</replaceable> is an arbitrary
      string which is processed accordingly depending on the
      <replaceable>name</replaceable>.  Setting up login classes and
      capabilities is rather straightforward and is also described in
      &man.login.conf.5;.</para>

    <note>
      <para>&os; does not normally read the configuration in
	<filename>/etc/login.conf</filename> directly, but instead
	reads the <filename>/etc/login.conf.db</filename> database
	which provides faster lookups.  Whenever
	<filename>/etc/login.conf</filename> is edited, the
	<filename>/etc/login.conf.db</filename> must be updated by
	executing the following command:</para>

      <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
    </note>

    <para>Resource limits differ from the default login capabilities
      in two ways.  First, for every limit, there is a soft (current)
      and hard limit.  A soft limit may be adjusted by the user or
      application, but may not be set higher than the hard limit.  The
      hard limit may be lowered by the user, but can only be raised
      by the superuser.  Second, most resource limits apply per
      process to a specific user, not to the user as a whole.  These
      differences are mandated by the specific handling of the limits,
      not by the implementation of the login capability
      framework.</para>

    <para>Below are the most commonly used resource limits.  The rest
      of the limits, along with all the other login capabilities, can
      be found in &man.login.conf.5;.</para>

    <variablelist>
      <varlistentry>
	<term><literal>coredumpsize</literal></term>

	<listitem>
	  <indexterm><primary>coredumpsize</primary></indexterm>
	  <indexterm><primary>limiting users</primary>
	    <secondary>coredumpsize</secondary>
	  </indexterm>
	  <para>The limit on the size of a core file generated by a
	    program is subordinate to other limits on disk usage, such
	    as <literal>filesize</literal>, or disk quotas.
	    This limit is often used as a less-severe method of
	    controlling disk space consumption.  Since users do not
	    generate core files themselves, and often do not delete
	    them, setting this may save them from running out of disk
	    space should a large program crash.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>cputime</literal></term>

	<listitem>
	  <indexterm><primary>cputime</primary></indexterm>
	  <indexterm>
	    <primary>limiting users</primary>
	    <secondary>cputime</secondary>
	  </indexterm>
	  <para>The maximum amount of CPU time a user's process may
	    consume.  Offending processes will be killed by the
	    kernel.</para>

	  <note>
	    <para>This is a limit on CPU <emphasis>time</emphasis>
	      consumed, not percentage of the CPU as displayed in
	      some fields by &man.top.1; and &man.ps.1;.</para>
	  </note>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>filesize</literal></term>

	<listitem>
	  <indexterm><primary>filesize</primary></indexterm>
	  <indexterm>
	    <primary>limiting users</primary>
	    <secondary>filesize</secondary>
	  </indexterm>
	  <para>The maximum size of a file the user may own.  Unlike
	    <link linkend="quotas">disk quotas</link>, this limit is
	    enforced on individual files, not the set of all files a
	    user owns.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>maxproc</literal></term>

	<listitem>
	  <indexterm><primary>maxproc</primary></indexterm>
	  <indexterm>
	    <primary>limiting users</primary>
	    <secondary>maxproc</secondary>
	  </indexterm>
	  <para>The maximum number of processes a user can run.  This
	    includes foreground and background processes.  This limit
	    may not be larger than the system limit specified by the
	    <varname>kern.maxproc</varname> &man.sysctl.8;.  Setting
	    this limit too small may hinder a user's productivity as
	    it is often useful to be logged in multiple times or to
	    execute pipelines.  Some tasks, such as compiling a large
	    program, spawn multiple processes and other intermediate
	    preprocessors.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>memorylocked</literal></term>

	<listitem>
	  <indexterm><primary>memorylocked</primary></indexterm>
	  <indexterm>
	    <primary>limiting users</primary>
	    <secondary>memorylocked</secondary>
	  </indexterm>
	  <para>The maximum amount of memory a process may request
	    to be locked into main memory using &man.mlock.2;.  Some
	    system-critical programs, such as &man.amd.8;, lock into
	    main memory so that if the system begins to swap, they do
	    not contribute to disk thrashing.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>memoryuse</literal></term>

	<listitem>
	  <indexterm><primary>memoryuse</primary></indexterm>
	  <indexterm><primary>limiting users</primary>
	    <secondary>memoryuse</secondary></indexterm>
	  <para>The maximum amount of memory a process may consume at
	    any given time.  It includes both core memory and swap
	    usage.  This is not a catch-all limit for restricting
	    memory consumption, but is a good start.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>openfiles</literal></term>

	<listitem>
	  <indexterm><primary>openfiles</primary></indexterm>
	  <indexterm><primary>limiting users</primary>
	    <secondary>openfiles</secondary>
	  </indexterm>
	  <para>The maximum number of files a process may have open.
	    In &os;, files are used to represent sockets and IPC
	    channels, so be careful not to set this too low.  The
	    system-wide limit for this is defined by the
	    <varname>kern.maxfiles</varname> &man.sysctl.8;.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>sbsize</literal></term>

	<listitem>
	  <indexterm><primary>sbsize</primary></indexterm>
	  <indexterm><primary>limiting users</primary>
	    <secondary>sbsize</secondary>
	  </indexterm>
	  <para>The limit on the amount of network memory, and
	    thus mbufs, a user may consume in order to limit network
	    communications.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>stacksize</literal></term>

	<listitem>
	  <indexterm><primary>stacksize</primary></indexterm>
	  <indexterm><primary>limiting users</primary>
	    <secondary>stacksize</secondary>
	  </indexterm>
	  <para>The maximum size of a process stack.  This alone is
	    not sufficient to limit the amount of memory a program
	    may use so it should be used in conjunction with other
	    limits.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>There are a few other things to remember when setting
      resource limits.  Following are some general tips, suggestions,
      and miscellaneous comments.</para>

    <itemizedlist>
      <listitem>
	<para>Processes started at system startup by
	  <filename>/etc/rc</filename> are assigned to the
	  <literal>daemon</literal> login class.</para>
      </listitem>

      <listitem>
	<para>Although the <filename>/etc/login.conf</filename> that
	  comes with the system is a good source of reasonable values
	  for most limits, they may not be appropriate for every
	  system.  Setting a limit too high may open the system up to
	  abuse, while setting it too low may put a strain on
	  productivity.</para>
      </listitem>

      <listitem>
	<para>Users of <application>&xorg;</application> should
	  probably be granted more resources than other users.
	  <application>&xorg;</application> by itself takes a lot of
	  resources, but it also encourages users to run more programs
	  simultaneously.</para>
      </listitem>

      <listitem>
	<para>Many limits apply to individual processes, not the user
	  as a whole.  For example, setting
	  <varname>openfiles</varname> to 50 means that each process
	  the user runs may open up to 50 files.  The total amount
	  of files a user may open is the value of
	  <literal>openfiles</literal> multiplied by the value of
	  <literal>maxproc</literal>.  This also applies to memory
	  consumption.</para>
      </listitem>
    </itemizedlist>

    <para>For further information on resource limits and login classes
      and capabilities in general, refer to &man.cap.mkdb.1;,
      &man.getrlimit.2;, and &man.login.conf.5;.</para>
  </sect1>

  <sect1 id="users-groups">
    <title>Groups</title>

    <indexterm><primary>groups</primary></indexterm>
    <indexterm>
      <primary><filename>/etc/groups</filename></primary>
    </indexterm>
    <indexterm>
      <primary>accounts</primary>
      <secondary>groups</secondary>
    </indexterm>
    <para>A group is a list of users.  A group is identified by its
      group name and <acronym>GID</acronym>.  In &os;, the
      kernel uses the <acronym>UID</acronym> of a process, and the
      list of groups it belongs to, to determine what the process is
      allowed to do.  Most of the time, the <acronym>GID</acronym> of
      a user or process usually means the first group in the
      list.</para>

    <para>The group name to <acronym>GID</acronym> mapping is listed
      in <filename>/etc/group</filename>.  This is a plain text file
      with four colon-delimited fields.  The first field is the group
      name, the second is the encrypted password, the third the
      <acronym>GID</acronym>, and the fourth the comma-delimited list
      of members.  For a more complete description of the syntax,
      refer to &man.group.5;.</para>

    <para>The superuser can modify <filename>/etc/group</filename>
      using a text editor.  Alternatively, &man.pw.8; can be used to
      add and edit groups.  For example, to add a group called
      <groupname>teamtwo</groupname> and then confirm that it
      exists:</para>

    <example>
      <title>Adding a Group Using &man.pw.8;</title>

      <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput>
&prompt.root; <userinput>pw groupshow teamtwo</userinput>
teamtwo:*:1100:</screen>
    </example>

    <para>In this example, <literal>1100</literal> is the
      <acronym>GID</acronym> of <groupname>teamtwo</groupname>.  Right
      now, <groupname>teamtwo</groupname> has no members.  This
      command will add <username>jru</username> as a member of
      <groupname>teamtwo</groupname>.</para>

    <example>
      <title>Adding User Accounts to a New Group Using
	&man.pw.8;</title>

      <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput>
&prompt.root; <userinput>pw groupshow teamtwo</userinput>
teamtwo:*:1100:jru</screen>
    </example>

    <para>The argument to <option>-M</option> is a comma-delimited
      list of users to be added to a new (empty) group or to replace
      the members of an existing group.  To the user, this group
      membership is different from (and in addition to) the user's
      primary group listed in the password file.  This means that
      the user will not show up as a member when using
      <option>groupshow</option> with &man.pw.8;, but will show up
      when the information is queried via &man.id.1; or a similar
      tool.  When &man.pw.8; is used to add a user to a group, it only
      manipulates <filename>/etc/group</filename> and does not attempt
      to read additional data from
      <filename>/etc/passwd</filename>.</para>

    <example>
      <title>Adding a New Member to a Group Using &man.pw.8;</title>

      <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput>
&prompt.root; <userinput>pw groupshow teamtwo</userinput>
teamtwo:*:1100:jru,db</screen>
    </example>

    <para>In this example, the argument to <option>-m</option> is a
      comma-delimited list of users who are to be added to the group.
      Unlike the previous example, these users are appended to the
      group list and do not replace the list of existing users in the
      group.</para>

    <example>
      <title>Using &man.id.1; to Determine Group Membership</title>

      <screen>&prompt.user; <userinput>id jru</userinput>
uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen>
    </example>

    <para>In this example, <username>jru</username> is a member of the
      groups <groupname>jru</groupname> and
      <groupname>teamtwo</groupname>.</para>

    <para>For more information about this command and the format of
      <filename>/etc/group</filename>, refer to &man.pw.8; and
      &man.group.5;.</para>
  </sect1>
</chapter>