xref: /freebsd/lib/libutil/login_class.3 (revision 6b3ced11a2b9225041e40efc39c5ffbcda94dab1)
168bbf3adSDavid Nugent.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
268bbf3adSDavid Nugent.\" All rights reserved.
368bbf3adSDavid Nugent.\"
468bbf3adSDavid Nugent.\" Redistribution and use in source and binary forms, with or without
568bbf3adSDavid Nugent.\" modification, is permitted provided that the following conditions
668bbf3adSDavid Nugent.\" are met:
768bbf3adSDavid Nugent.\" 1. Redistributions of source code must retain the above copyright
868bbf3adSDavid Nugent.\"    notice immediately at the beginning of the file, without modification,
968bbf3adSDavid Nugent.\"    this list of conditions, and the following disclaimer.
1068bbf3adSDavid Nugent.\" 2. Redistributions in binary form must reproduce the above copyright
1168bbf3adSDavid Nugent.\"    notice, this list of conditions and the following disclaimer in the
1268bbf3adSDavid Nugent.\"    documentation and/or other materials provided with the distribution.
1368bbf3adSDavid Nugent.\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
1468bbf3adSDavid Nugent.\"    is permitted provided this notation is included.
1568bbf3adSDavid Nugent.\" 4. Absolutely no warranty of function or purpose is made by the author
1668bbf3adSDavid Nugent.\"    David Nugent.
1768bbf3adSDavid Nugent.\" 5. Modifications may be freely made to this file providing the above
1868bbf3adSDavid Nugent.\"    conditions are met.
1968bbf3adSDavid Nugent.\"
207f3dea24SPeter Wemm.\" $FreeBSD$
2168bbf3adSDavid Nugent.\"
2268bbf3adSDavid Nugent.Dd December 28, 1996
2368bbf3adSDavid Nugent.Os FreeBSD
2468bbf3adSDavid Nugent.Dt LOGIN_CLASS 3
2568bbf3adSDavid Nugent.Sh NAME
2668bbf3adSDavid Nugent.Nm setclasscontext ,
2768bbf3adSDavid Nugent.Nm setusercontext ,
2868bbf3adSDavid Nugent.Nm setclassresources ,
2968bbf3adSDavid Nugent.Nm setclassenvironment
3068bbf3adSDavid Nugent.Nd functions for using the login class capabilities database.
3168bbf3adSDavid Nugent.Sh SYNOPSIS
3268bbf3adSDavid Nugent.Fd #include <sys/types.h>
3368bbf3adSDavid Nugent.Fd #include <login_cap.h>
3468bbf3adSDavid Nugent.Ft int
35c5a44d91SBruce Evans.Fn setclasscontext "const char *classname" "unsigned int flags"
3668bbf3adSDavid Nugent.Ft int
3768bbf3adSDavid Nugent.Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
3868bbf3adSDavid Nugent.Ft void
3968bbf3adSDavid Nugent.Fn setclassresources "login_cap_t *lc"
4068bbf3adSDavid Nugent.Ft void
4168bbf3adSDavid Nugent.Fn setclassenvironment "login_cap_t *lc" "const struct passwd *pwd" "int paths"
4268bbf3adSDavid Nugent.Pp
4368bbf3adSDavid Nugent.Sh DESCRIPTION
4468bbf3adSDavid NugentThese functions provide a higher level interface to the login class
4568bbf3adSDavid Nugentdatabase than those documented in
4668bbf3adSDavid Nugent.Xr login_cap 3 .
4768bbf3adSDavid NugentThese functions are used to set resource limits, environment and
4868bbf3adSDavid Nugentaccounting settings for users on logging into the system and when
4968bbf3adSDavid Nugentselecting an appropriate set of environment and resource settings
5068bbf3adSDavid Nugentfor system daemons based on login classes.
5168bbf3adSDavid NugentThese functions may only be called if the current process is
529c727d2cSJoseph Koshyrunning with root privileges.
5368bbf3adSDavid NugentIf the LOGIN_SETLOGIN flag is used this function calls
5468bbf3adSDavid Nugent.Xr setlogin 2 ,
5568bbf3adSDavid Nugentand due care must be taken as detailed in the manpage for that
5668bbf3adSDavid Nugentfunction and this affects all processes running in the same session
5768bbf3adSDavid Nugentand not just the current process.
5868bbf3adSDavid Nugent.Pp
5968bbf3adSDavid Nugent.Fn setclasscontext
6068bbf3adSDavid Nugentsets various class context values (resource limits, umask and
6168bbf3adSDavid Nugentprocess priorities) based on values for a specific named class.
6268bbf3adSDavid Nugent.Pp
6368bbf3adSDavid NugentThe function
6468bbf3adSDavid Nugent.Fn setusercontext
6568bbf3adSDavid Nugentsets class context values based on a given login_cap_t
6668bbf3adSDavid Nugentobject, a specific passwd record (if login_cap_t is NULL),
6768bbf3adSDavid Nugentsets the current session's login and the current process
6868bbf3adSDavid Nugentuser and group ownership.
6968bbf3adSDavid NugentEach of these functions is selectable via bit-flags passed
7068bbf3adSDavid Nugentin the
7168bbf3adSDavid Nugent.Ar flags
7268bbf3adSDavid Nugentparameter, which is comprised of one or more of the following:
7368bbf3adSDavid Nugent.Bl -tag -width LOGIN_SETRESOURCES
7468bbf3adSDavid Nugent.It LOGIN_SETLOGIN
7568bbf3adSDavid NugentSet the login associated with the current session to the user
7668bbf3adSDavid Nugentspecified in the passwd structure.
7768bbf3adSDavid Nugent.Xr setlogin 2 .
7868bbf3adSDavid NugentThe
7968bbf3adSDavid Nugent.Ar pwd
8068bbf3adSDavid Nugentparameter must not be NULL if this option is used.
8168bbf3adSDavid Nugent.It LOGIN_SETUSER
8268bbf3adSDavid NugentSet ownship of the current process to the uid specified in the
8368bbf3adSDavid Nugent.Ar uid
8468bbf3adSDavid Nugentparameter using
8568bbf3adSDavid Nugent.Xr setuid 2 .
8668bbf3adSDavid Nugent.It LOGIN_SETGROUP
8768bbf3adSDavid NugentSet group ownership of the current process to the group id
8868bbf3adSDavid Nugentspecified in the passwd structure using
8968bbf3adSDavid Nugent.Xr setgid 2 ,
9068bbf3adSDavid Nugentand calls
9168bbf3adSDavid Nugent.Xr initgroups 3
9268bbf3adSDavid Nugentto set up the group access list for the current process.
9368bbf3adSDavid NugentThe
9468bbf3adSDavid Nugent.Ar pwd
9568bbf3adSDavid Nugentparameter must not be NULL if this option is used.
9668bbf3adSDavid Nugent.It LOGIN_SETRESOURCES
9768bbf3adSDavid NugentSet resource limits for the current process based on values
9868bbf3adSDavid Nugentspecified in the system login class database.
9968bbf3adSDavid NugentClass capability tags used, with and without -cur (soft limit)
10068bbf3adSDavid Nugentor -max (hard limit) suffixes and the corresponding resource
10168bbf3adSDavid Nugentsetting:
10268bbf3adSDavid Nugent.Bd -literal
10368bbf3adSDavid Nugentcputime       RLIMIT_CPU
10468bbf3adSDavid Nugentfilesize      RLIMIT_FSIZE
10568bbf3adSDavid Nugentdatasize      RLIMIT_DATA
10668bbf3adSDavid Nugentstacksize     RLIMIT_STACK
10768bbf3adSDavid Nugentcoredumpsize  RLIMIT_CORE
10868bbf3adSDavid Nugentmemoryuse     RLIMIT_RSS
10968bbf3adSDavid Nugentmemorylocked  RLIMIT_MEMLOCK
11068bbf3adSDavid Nugentmaxproc       RLIMIT_NPROC
11168bbf3adSDavid Nugentopenfiles     RLIMIT_NOFILE
1126b3ced11SBrian Feldmansbsize        RLIMIT_SBSIZE
11368bbf3adSDavid Nugent.Ed
11468bbf3adSDavid Nugent.It LOGIN_SETPRIORITY
11568bbf3adSDavid NugentSet the scheduling priority for the current process based on the
11668bbf3adSDavid Nugentvalue specified in the system login class database.
11768bbf3adSDavid NugentClass capability tags used:
11868bbf3adSDavid Nugent.Bd -literal
11968bbf3adSDavid Nugentpriority
12068bbf3adSDavid Nugent.Ed
12168bbf3adSDavid Nugent.It LOGIN_SETUMASK
12268bbf3adSDavid NugentSet the umask for the current process to a value in the user or
12368bbf3adSDavid Nugentsystem login class database.
12468bbf3adSDavid NugentClass capability tags used:
12568bbf3adSDavid Nugent.Bd -literal
12668bbf3adSDavid Nugentumask
12768bbf3adSDavid Nugent.Ed
12868bbf3adSDavid Nugent.It LOGIN_SETPATH
12968bbf3adSDavid NugentSet the "path" and "manpath" environment variables based on values
13068bbf3adSDavid Nugentin the user or system login class database.
13168bbf3adSDavid NugentClass capability tags used with the corresponding environment
13268bbf3adSDavid Nugentvariables set:
13368bbf3adSDavid Nugent.Bd -literal
13468bbf3adSDavid Nugentpath          PATH
13568bbf3adSDavid Nugentmanpath       MANPATH
13668bbf3adSDavid Nugent.Ed
13768bbf3adSDavid Nugent.It LOGIN_SETENV
13868bbf3adSDavid NugentSet various environment variables based on values in the user or
13968bbf3adSDavid Nugentsystem login class database.
14068bbf3adSDavid NugentClass capability tags used with the corresponding environment
14168bbf3adSDavid Nugentvariables set:
14268bbf3adSDavid Nugent.Bd -literal
14368bbf3adSDavid Nugentlang          LANG
14468bbf3adSDavid Nugentcharset       MM_CHARSET
14568bbf3adSDavid Nugenttimezone      TZ
14668bbf3adSDavid Nugentterm          TERM
14768bbf3adSDavid Nugent.Ed
14868bbf3adSDavid Nugent.Pp
14968bbf3adSDavid NugentAdditional environment variables may be set using the list type
15068bbf3adSDavid Nugentcapability "setenv=var1 val1,var2 val2..,varN valN".
15168bbf3adSDavid Nugent.It LOGIN_SETALL
15268bbf3adSDavid NugentEnables all of the above settings.
15368bbf3adSDavid Nugent.El
15468bbf3adSDavid Nugent.Pp
15568bbf3adSDavid NugentNote that when setting environment variables and a valid passwd
15668bbf3adSDavid Nugentpointer is provided in the
15768bbf3adSDavid Nugent.Ar pwd
15868bbf3adSDavid Nugentparameter, the characters
15968bbf3adSDavid Nugent.Ql \&~
16068bbf3adSDavid Nugentand
16168bbf3adSDavid Nugent.Ql \&$
16268bbf3adSDavid Nugentare substituted for the user's home directory and login name
16368bbf3adSDavid Nugentrespectively.
16468bbf3adSDavid Nugent.Pp
16568bbf3adSDavid NugentThe
16668bbf3adSDavid Nugent.Fn setclassresources
16768bbf3adSDavid Nugentand
16868bbf3adSDavid Nugent.Fn setclassenvironment
16968bbf3adSDavid Nugentfunctions are subsets of the setcontext functions above, but may
17068bbf3adSDavid Nugentbe useful in isolation.
17168bbf3adSDavid Nugent.Sh RETURN VALUES
17268bbf3adSDavid Nugent.Fn setclasscontext
17368bbf3adSDavid Nugentand
17468bbf3adSDavid Nugent.Fn setusercontext
1759c727d2cSJoseph Koshyreturn -1 if an error occurred, or 0 on success.
17668bbf3adSDavid NugentIf an error occurs when attempting to set the user, login, group
17768bbf3adSDavid Nugentor resources, a message is reported to
17868bbf3adSDavid Nugent.Xr syslog 3 ,
17968bbf3adSDavid Nugentwith LOG_ERR priority and directed to the currently active facility.
18068bbf3adSDavid Nugent.Sh SEE ALSO
18175141cc9SWolfram Schneider.Xr setgid 2 ,
18268bbf3adSDavid Nugent.Xr setlogin 2 ,
18368bbf3adSDavid Nugent.Xr setuid 2 ,
18475141cc9SWolfram Schneider.Xr getcap 3 ,
18568bbf3adSDavid Nugent.Xr initgroups 3 ,
18668bbf3adSDavid Nugent.Xr login_cap 3 ,
18768bbf3adSDavid Nugent.Xr login.conf 5 ,
18875141cc9SWolfram Schneider.Xr termcap 5
189