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 March 24, 2011
  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 .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 .Pp
 163 .It LOGIN_SETCPUMASK
 164 Create a new
 165 .Xr cpuset 2
 166 and set the cpu affinity to the specified mask.
 167 The string may contain a comma separated list of numbers and/or number
 168 ranges as handled by the
 169 .Xr cpuset 1
 170 utility or the case-insensitive string
 171 .Ql default .
 172 If the string is
 173 .Ql default
 174 no action will be taken.
 175 .It LOGIN_SETLOGINCLASS
 176 Set the login class of the current process using
 177 .Xr setloginclass 2 .
 178 .It LOGIN_SETALL
 179 Enables all of the above settings.
 180 .El
 181 .Pp
 182 Note that when setting environment variables and a valid passwd
 183 pointer is provided in the
 184 .Ar pwd
 185 parameter, the characters
 186 .Ql \&~
 187 and
 188 .Ql \&$
 189 are substituted for the user's home directory and login name
 190 respectively.
 191 .Pp
 192 The
 193 .Fn setclasscpumask ,
 194 .Fn setclassresources
 195 and
 196 .Fn setclassenvironment
 197 functions are subsets of the setcontext functions above, but may
 198 be useful in isolation.
 199 .Sh RETURN VALUES
 200 The
 201 .Fn setclasscontext
 202 and
 203 .Fn setusercontext
 204 functions return -1 if an error occurred, or 0 on success.
 205 If an error occurs when attempting to set the user, login, group
 206 or resources, a message is reported to
 207 .Xr syslog 3 ,
 208 with LOG_ERR priority and directed to the currently active facility.
 209 .Sh SEE ALSO
 210 .Xr cpuset 1 ,
 211 .Xr ps 1 ,
 212 .Xr cpuset 2 ,
 213 .Xr setgid 2 ,
 214 .Xr setlogin 2 ,
 215 .Xr setloginclass 2 ,
 216 .Xr setuid 2 ,
 217 .Xr getcap 3 ,
 218 .Xr initgroups 3 ,
 219 .Xr login_cap 3 ,
 220 .Xr mac_set_proc 3 ,
 221 .Xr login.conf 5 ,
 222 .Xr termcap 5