xref: /dragonfly/lib/libutil/login_class.3 (revision cfd1aba3) 
1.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, is permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice immediately at the beginning of the file, without modification,
9.\"    this list of conditions, and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
14.\"    is permitted provided this notation is included.
15.\" 4. Absolutely no warranty of function or purpose is made by the author
16.\"    David Nugent.
17.\" 5. Modifications may be freely made to this file providing the above
18.\"    conditions are met.
19.\"
20.\" $FreeBSD: src/lib/libutil/login_class.3,v 1.9.2.4 2003/04/29 14:40:07 trhodes Exp $
21.\"
22.Dd December 28, 1996
23.Dt LOGIN_CLASS 3
24.Os
25.Sh NAME
26.Nm setclasscontext ,
27.Nm setclassenvironment ,
28.Nm setclassresources ,
29.Nm setusercontext
30.Nd "functions for using the login class capabilities database"
31.Sh LIBRARY
32.Lb libutil
33.Sh SYNOPSIS
34.In sys/types.h
35.In login_cap.h
36.Ft int
37.Fn setclasscontext "const char *classname" "unsigned int flags"
38.Ft int
39.Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
40.Ft void
41.Fn setclassresources "login_cap_t *lc"
42.Ft void
43.Fn setclassenvironment "login_cap_t *lc" "const struct passwd *pwd" "int paths"
44.Sh DESCRIPTION
45These functions provide a higher level interface to the login class
46database than those documented in
47.Xr login_cap 3 .
48These functions are used to set resource limits, environment and
49accounting settings for users on logging into the system and when
50selecting an appropriate set of environment and resource settings
51for system daemons based on login classes.
52These functions may only be called if the current process is
53running with root privileges.
54If the LOGIN_SETLOGIN flag is used this function calls
55.Xr setlogin 2 ,
56and due care must be taken as detailed in the manpage for that
57function and this affects all processes running in the same session
58and not just the current process.
59.Pp
60.Fn setclasscontext
61sets various class context values (resource limits, umask and
62process priorities) based on values for a specific named class.
63.Pp
64The function
65.Fn setusercontext
66sets class context values based on a given login_cap_t
67object, a specific passwd record (if login_cap_t is NULL),
68sets the current session's login and the current process
69user and group ownership.
70Each of these functions is selectable via bit-flags passed
71in the
72.Ar flags
73parameter, which is comprised of one or more of the following:
74.Bl -tag -width LOGIN_SETRESOURCES
75.It LOGIN_SETLOGIN
76Set the login associated with the current session to the user
77specified in the passwd structure.
78.Xr setlogin 2 .
79The
80.Ar pwd
81parameter must not be NULL if this option is used.
82.It LOGIN_SETUSER
83Set ownership of the current process to the uid specified in the
84.Ar uid
85parameter using
86.Xr setuid 2 .
87.It LOGIN_SETGROUP
88Set group ownership of the current process to the group id
89specified in the passwd structure using
90.Xr setgid 2 ,
91and calls
92.Xr initgroups 3
93to set up the group access list for the current process.
94The
95.Ar pwd
96parameter must not be NULL if this option is used.
97.It LOGIN_SETRESOURCES
98Set resource limits for the current process based on values
99specified in the system login class database.
100Class capability tags used, with and without -cur (soft limit)
101or -max (hard limit) suffixes and the corresponding resource
102setting:
103.Bd -literal
104cputime       RLIMIT_CPU
105filesize      RLIMIT_FSIZE
106datasize      RLIMIT_DATA
107stacksize     RLIMIT_STACK
108coredumpsize  RLIMIT_CORE
109memoryuse     RLIMIT_RSS
110memorylocked  RLIMIT_MEMLOCK
111maxproc       RLIMIT_NPROC
112openfiles     RLIMIT_NOFILE
113sbsize        RLIMIT_SBSIZE
114vmemoryuse    RLIMIT_VMEM
115.Ed
116.It LOGIN_SETPRIORITY
117Set the scheduling priority for the current process based on the
118value specified in the system login class database.
119Class capability tags used:
120.Bd -literal
121priority
122.Ed
123.It LOGIN_SETUMASK
124Set the umask for the current process to a value in the user or
125system login class database.
126Class capability tags used:
127.Bd -literal
128umask
129.Ed
130.It LOGIN_SETPATH
131Set the "path" and "manpath" environment variables based on values
132in the user or system login class database.
133Class capability tags used with the corresponding environment
134variables set:
135.Bd -literal
136path          PATH
137manpath       MANPATH
138.Ed
139.It LOGIN_SETENV
140Set various environment variables based on values in the user or
141system login class database.
142Class capability tags used with the corresponding environment
143variables set:
144.Bd -literal
145lang          LANG
146charset       MM_CHARSET
147timezone      TZ
148term          TERM
149.Ed
150.Pp
151Additional environment variables may be set using the list type
152capability "setenv=var1 val1,var2 val2..,varN valN".
153.It LOGIN_SETALL
154Enables all of the above settings.
155.El
156.Pp
157Note that when setting environment variables and a valid passwd
158pointer is provided in the
159.Ar pwd
160parameter, the characters
161.Ql \&~
162and
163.Ql \&$
164are substituted for the user's home directory and login name
165respectively.
166.Pp
167The
168.Fn setclassresources
169and
170.Fn setclassenvironment
171functions are subsets of the setcontext functions above, but may
172be useful in isolation.
173.Sh RETURN VALUES
174The
175.Fn setclasscontext
176and
177.Fn setusercontext
178functions return -1 if an error occurred, or 0 on success.
179If an error occurs when attempting to set the user, login, group
180or resources, a message is reported to
181.Xr syslog 3 ,
182with LOG_ERR priority and directed to the currently active facility.
183.Sh ERRORS
184.Bl -tag -width Er
185.It Bq Er ENOMEM
186The function
187.Fn setclassenvironment
188failed because it were unable to allocate memory for the environment.
189.El
190.Sh SEE ALSO
191.Xr setgid 2 ,
192.Xr setlogin 2 ,
193.Xr setuid 2 ,
194.Xr getcap 3 ,
195.Xr initgroups 3 ,
196.Xr login_cap 3 ,
197.Xr login.conf 5 ,
198.Xr termcap 5
199