lib/libutil/login_class.3

   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 .Dd May 10, 2020
  21 .Dt LOGIN_CLASS 3
  22 .Os
  23 .Sh NAME
  24 .Nm setclasscontext ,
  25 .Nm setclasscpumask ,
  26 .Nm setclassenvironment ,
  27 .Nm setclassresources ,
  28 .Nm setusercontext
  29 .Nd "functions for using the login class capabilities database"
  30 .Sh LIBRARY
  31 .Lb libutil
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In login_cap.h
  35 .Ft int
  36 .Fn setclasscontext "const char *classname" "unsigned int flags"
  37 .Ft void
  38 .Fn setclasscpumask "login_cap_t *lc"
  39 .Ft void
  40 .Fn setclassenvironment "login_cap_t *lc" "const struct passwd *pwd" "int paths"
  41 .Ft void
  42 .Fn setclassresources "login_cap_t *lc"
  43 .Ft int
  44 .Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
  45 .Sh DESCRIPTION
  46 These functions provide a higher level interface to the login class
  47 database than those documented in
  48 .Xr login_cap 3 .
  49 These functions are used to set resource limits, environment and
  50 accounting settings for users on logging into the system and when
  51 selecting an appropriate set of environment and resource settings
  52 for system daemons based on login classes.
  53 These functions may only be called if the current process is
  54 running with root privileges.
  55 If the LOGIN_SETLOGIN flag is used this function calls
  56 .Xr setlogin 2 ,
  57 and due care must be taken as detailed in the manpage for that
  58 function and this affects all processes running in the same session
  59 and not just the current process.
  60 .Pp
  61 The
  62 .Fn setclasscontext
  63 function sets various class context values (resource limits, umask and
  64 process priorities) based on values for a specific named class.
  65 .Pp
  66 The
  67 .Fn setusercontext
  68 function sets class context values based on a given login_cap_t
  69 object and a specific passwd record (if login_cap_t is NULL),
  70 the current session's login, and the current process
  71 user and group ownership.
  72 Each of these actions is selectable via bit-flags passed
  73 in the
  74 .Ar flags
  75 parameter, which is comprised of one or more of the following:
  76 .Bl -tag -width LOGIN_SETLOGINCLASS
  77 .It LOGIN_SETLOGIN
  78 Set the login associated with the current session to the user
  79 specified in the passwd structure using
  80 .Xr setlogin 2 .
  81 The
  82 .Ar pwd
  83 parameter must not be NULL if this option is used.
  84 .It LOGIN_SETUSER
  85 Set ownership of the current process to the uid specified in the
  86 .Ar uid
  87 parameter using
  88 .Xr setuid 2 .
  89 .It LOGIN_SETGROUP
  90 Set group ownership of the current process to the group id
  91 specified in the passwd structure using
  92 .Xr setgid 2 ,
  93 and calls
  94 .Xr initgroups 3
  95 to set up the group access list for the current process.
  96 The
  97 .Ar pwd
  98 parameter must not be NULL if this option is used.
  99 .It LOGIN_SETRESOURCES
 100 Set resource limits for the current process based on values
 101 specified in the system login class database.
 102 Class capability tags used, with and without -cur (soft limit)
 103 or -max (hard limit) suffixes and the corresponding resource
 104 setting:
 105 .Bd -literal
 106 cputime          RLIMIT_CPU
 107 filesize         RLIMIT_FSIZE
 108 datasize         RLIMIT_DATA
 109 stacksize        RLIMIT_STACK
 110 coredumpsize     RLIMIT_CORE
 111 memoryuse        RLIMIT_RSS
 112 memorylocked     RLIMIT_MEMLOCK
 113 maxproc          RLIMIT_NPROC
 114 openfiles        RLIMIT_NOFILE
 115 sbsize           RLIMIT_SBSIZE
 116 vmemoryuse       RLIMIT_VMEM
 117 pseudoterminals  RLIMIT_NPTS
 118 swapuse          RLIMIT_SWAP
 119 kqueues          RLIMIT_KQUEUES
 120 umtxp            RLIMIT_UMTXP
 121 .Ed
 122 .It LOGIN_SETPRIORITY
 123 Set the scheduling priority for the current process based on the
 124 value specified in the system login class database.
 125 Class capability tags used:
 126 .Bd -literal
 127 priority
 128 .Ed
 129 .It LOGIN_SETUMASK
 130 Set the umask for the current process to a value in the user or
 131 system login class database.
 132 Class capability tags used:
 133 .Bd -literal
 134 umask
 135 .Ed
 136 .It LOGIN_SETPATH
 137 Set the "path" and "manpath" environment variables based on values
 138 in the user or system login class database.
 139 Class capability tags used with the corresponding environment
 140 variables set:
 141 .Bd -literal
 142 path          PATH
 143 manpath       MANPATH
 144 .Ed
 145 .It LOGIN_SETENV
 146 Set various environment variables based on values in the user or
 147 system login class database.
 148 Class capability tags used with the corresponding environment
 149 variables set:
 150 .Bd -literal
 151 lang          LANG
 152 charset       MM_CHARSET
 153 timezone      TZ
 154 term          TERM
 155 .Ed
 156 .Pp
 157 Additional environment variables may be set using the list type
 158 capability "setenv=var1 val1,var2 val2..,varN valN".
 159 .It LOGIN_SETMAC
 160 Set the MAC label for the current process to the label specified
 161 in system login class database.
 162 .It LOGIN_SETCPUMASK
 163 Create a new
 164 .Xr cpuset 2
 165 and set the cpu affinity to the specified mask.
 166 The string may contain a comma separated list of numbers and/or number
 167 ranges as handled by the
 168 .Xr cpuset 1
 169 utility or the case-insensitive string
 170 .Ql default .
 171 If the string is
 172 .Ql default
 173 no action will be taken.
 174 .It LOGIN_SETLOGINCLASS
 175 Set the login class of the current process using
 176 .Xr setloginclass 2 .
 177 .It LOGIN_SETALL
 178 Enables all of the above settings.
 179 .El
 180 .Pp
 181 Note that when setting environment variables and a valid passwd
 182 pointer is provided in the
 183 .Ar pwd
 184 parameter, the characters
 185 .Ql \&~
 186 and
 187 .Ql \&$
 188 are substituted for the user's home directory and login name
 189 respectively.
 190 .Pp
 191 The
 192 .Fn setclasscpumask ,
 193 .Fn setclassresources
 194 and
 195 .Fn setclassenvironment
 196 functions are subsets of the setcontext functions above, but may
 197 be useful in isolation.
 198 .Sh RETURN VALUES
 199 The
 200 .Fn setclasscontext
 201 and
 202 .Fn setusercontext
 203 functions return -1 if an error occurred, or 0 on success.
 204 If an error occurs when attempting to set the user, login, group
 205 or resources, a message is reported to
 206 .Xr syslog 3 ,
 207 with LOG_ERR priority and directed to the currently active facility.
 208 .Sh SEE ALSO
 209 .Xr cpuset 1 ,
 210 .Xr ps 1 ,
 211 .Xr cpuset 2 ,
 212 .Xr setgid 2 ,
 213 .Xr setlogin 2 ,
 214 .Xr setloginclass 2 ,
 215 .Xr setuid 2 ,
 216 .Xr getcap 3 ,
 217 .Xr initgroups 3 ,
 218 .Xr login_cap 3 ,
 219 .Xr mac_set_proc 3 ,
 220 .Xr login.conf 5 ,
 221 .Xr termcap 5
 222 .Sh HISTORY
 223 The functions
 224 .Fn setclasscontext ,
 225 .Fn setclasscpumask ,
 226 .Fn setclassenvironment ,
 227 .Fn setclassresources
 228 and
 229 .Fn setusercontext
 230 first appeared in
 231 .Fx 2.1.5 .