
Help file for 'seuser' Version 0.4
December 18, 2002
selinux@tresys.com


The seuser tool is intended to help an administrator manage user 
accounts with for the SELinux security policy.  The tool will ensure 
that all required policy elements are defined for a user before 
committing the changes and installing the new policy.

WARNING:  This is very much a first generation tool.  We apologize for 
the likely bugs.  Use with caution.  Send bug reports to 
selinux@tresys.com.


Changes in Default Login Contexts
---------------------------------

Circa October 2002, the way SELinux handles default login context has 
changed.  Previously (the old method), there was a default context 
file for both cron and login in /etc/security that defined default 
login contexts for users.  If a default context wasn't defined, the 
user could not login. Now (the new method), those files are no longer 
used and instead a default_contexts (with an "s") is in /etc/security. 
This defines preferences for default contexts for all users depending 
on the type of the login process.  Users can also override these 
system-wide defaults with a similar file in their home directory.

As a result, seuser has changed to support both the old and new login 
context styles.  The tool will detect which type is being used, and 
adjust accordingly.  In the old style you must provide a default cron 
and/or login context.  In the new style, seuser does nothing with 
default contexts.  The GUI adjusts its display based on the version. 
The command line interface will ignore the default cron and login 
contexts if provided.


Command line versus GUI
-----------------------

seuser can run from the command line, or via a GUI.  This help file is 
intended for the GUI which is started via seuser -g.  Run seuser -h 
for command line help.


SELinux Users Overview
-----------------------

In seuser, the term "system user" means a Linux user account as found 
in /etc/passwd.  The term "selinux user" means a system user that is 
also defined to the SELinux security policy.

This tool treats each user account as a user record.  It allows you to 
add and remove system users to the selinux policy. A valid user record 
must have one or more roles.  Also for the old login context style, a 
user must also have a default login or cron context (or both).  

NOTE: There are two special user names in SELinux: system_u and 
user_u. system_u is used for system processes and objects.  It should 
always exist in the policy; seuser will not allow you to remove 
system_u, although you can change its roles and default contexts.

user_u may or may not be in the policy.  If user_u IS defined in the 
policy, then any system user account that IS NOT defined in the policy 
will get the roles and default contexts defined for user_u. If user_u 
IS NOT defined in the policy, then all system users must be explicitly 
defined in the policy in order to login.


Tool Overview
-------------

The seuser tool consists of a single window displaying various 
information.  The tool allows you to both display and edit information 
for selinux user records.  The tool's edit model is fairly simple; you 
can only edit one record at a time.  You must either commit or cancel 
the changes to the current user record before viewing or editing 
another user record.

When the tool first starts, it reads the user databases from various 
locations and displays the information.  The seuser.conf file in the 
installed library directory indicates where the user database files 
are stored (see the readme file).  If the tool cannot find the 
seuser.conf file, or one of the indicated user database files, it will 
report an error and exit.


Tool Modes
----------

The tool has two modes: edit and view.  The status bar indicates which 
mode you are currently in.  You always start in view mode. The first 
time you make a change to a user record, the mode will change to edit 
mode.

There are three edit types that can cause you to go into edit mode:

     add:	add a new system user to SELinux
     delete:	remove an selinux user from the policy
     change:	change some aspect of an existing selinux user
     
The status bar will indicate which type of modification is occurring 
when in edit mode (in view mode, the edit type indicates "none").

As indicated, once in edit mode, you must either commit or cancel the 
changes before moving to a new record.


The Users Display
-----------------

The top third of the window contains two user lists.  The "system 
user" list shows all the Linux user accounts defined in /etc/passwd 
that are not currently defined in the selinux policy.  The "SELinux 
Users" list are those users that are defined to the policy.  The two 
arrow buttons allow you to delete and add users to the policy. These 
buttons will put you in edit mode, with a type of add or delete as 
appropriate.

The selinux user list may also show color coding on some user records
indicating that the record has a problem and should be corrected.  
The background color coding for the selinux user list is:

     clear/white:	All is well with the record
     
     red:		The user record is not well formed.  The problem
			will be with either the roles or the (for the old
			style of login) default	contexts.  Clicking on the 
			record will pop up a message indicating the problem.
                     
     yellow:		The record is well formed (otherwise it would
			be red), however, the user name is not a valid
			system user.  This means the policy knows of a user
			that the system does not.
                     
The one exception to "yellow" is the special user "system_u".  This 
user is a special case in SELinux and will never be yellowed. Likewise 
the tool will not allow you to delete it.

Any record defined via the tool will not have a color code problem; 
however manual editing of the policy files can cause the problems and 
hence the coding.


The Roles Display
-----------------

Like the users display, the roles display has two lists.  The 
"available roles" lists are all the roles currently defined in the 
policy that are not displayed in the "current roles" list, which are 
those role defined for the currently selected selinux user.  The arrow 
buttons allow you to add and remove roles from a user record.  If you 
are in view mode, hitting one of these buttons will put you in edit 
mode with a type of change.  The seuser tool does not support defining 
new roles; that's a more involved process and something we believe is 
not within the scope of changes that a system administrator would 
make.


The Default Contexts (Old Style of Login Context Only)
------------------------------------------------------

These items will not be displayed if the tool detects you're using a 
recent SELinux system with the new login style.

Each user can have two default contexts: login and cron.  A context is 
a triple of user, role, and domain type.  The user will always be the 
selected user name.  The role must be one of the current roles defined 
for the user.  The type must be one of the types allowed for the 
selected role.  The tool provides drop down boxes so you can select an 
appropriate role and type.

The login type is used to define the default security context for 
typical login for the user.  The cron context does the same for cron 
jobs.  All user records must have at least one default context defined 
in order to be a valid record.

A common choice in the distributed policy is to give ordinary new 
users the user_r role and user_t type as their default login context 
(and no default cron context).


The Buttons
-----------

Along the bottom are four buttons, which may or may not be available 
depending on the current mode of the tool.  In edit mode, the Commit 
and Cancel buttons are available, and the Refresh and Exit buttons 
are not.  As indicated, once in edit mode, you must either commit or 
cancel the changes before selecting another user record or exiting the 
tool.  

Commit will permanently write the changes to the appropriate files on 
disk as defined in the seuser.conf file.  While the changes are 
committed to disk, they are not installed.  This allows you to make 
many changes and commit them one at a time before installing them. 
The tool does not support the ability to "uncommit" changes; but you 
can avoid installing them (see below).

Cancel will simply unwind the changes made to the current record and 
switch back to view mode.

In view mode, the Refresh and Exit buttons are available, and the 
Commit and Cancel buttons are not.  

Refresh will reload the user database from the source files as if the 
tool had just started.  This is useful if, for example, you defined 
new system users while the tool was running and you want to update the 
list.  It is also useful if you don't completely trust the tool and 
want to verify that the updates are occurring (something we currently 
do a lot with this first generation tool).  Refresh may do an added 
step of rebuilding the policy.conf file before refreshing the display. 
This will be necessary if new users have been added or deleted, or if 
current roles have been changed.  It will not occur if only default 
contexts have been changed. You will not see anything if policy.conf 
is rebuilt, unless there is an error.

Exit will leave the program.  This is also the point at which you get 
your ONE AND ONLY chance to have the tool rebuild and install the 
changed policy (which will only be necessary if users were deleted or 
added, or if current roles were changed for a user).  If the "users 
file changed" a popup box comes up after clicking Exit, you are 
provided three choices:

    Yes:	This will re-make and install the new policy.  The changes
		are immediate.
	        
    No:		This will exit the tool, but leave the committed changes to
		disk.  In general you should not select this option unless
		you plan to manually run the make from the policy directory.
		Otherwise, the changes to the user files will be lost the
		next time the seuser tool runs, but the changes to the 
		default contexts will not.
	        
    Cancel:	Simply returns to the tool as if you hadn't clicked Exit.
        


