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