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 October 20, 2008
  23 .Os
  24 .Dt LOGIN_CLASS 3
  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_SETRESOURCES
  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 .Ed
 120 .It LOGIN_SETPRIORITY
 121 Set the scheduling priority for the current process based on the
 122 value specified in the system login class database.
 123 Class capability tags used:
 124 .Bd -literal
 125 priority
 126 .Ed
 127 .It LOGIN_SETUMASK
 128 Set the umask for the current process to a value in the user or
 129 system login class database.
 130 Class capability tags used:
 131 .Bd -literal
 132 umask
 133 .Ed
 134 .It LOGIN_SETPATH
 135 Set the "path" and "manpath" environment variables based on values
 136 in the user or system login class database.
 137 Class capability tags used with the corresponding environment
 138 variables set:
 139 .Bd -literal
 140 path          PATH
 141 manpath       MANPATH
 142 .Ed
 143 .It LOGIN_SETENV
 144 Set various environment variables based on values in the user or
 145 system login class database.
 146 Class capability tags used with the corresponding environment
 147 variables set:
 148 .Bd -literal
 149 lang          LANG
 150 charset       MM_CHARSET
 151 timezone      TZ
 152 term          TERM
 153 .Ed
 154 .Pp
 155 Additional environment variables may be set using the list type
 156 capability "setenv=var1 val1,var2 val2..,varN valN".
 157 .It LOGIN_SETMAC
 158 Set the MAC label for the current process to the label specified
 159 in system login class database.
 160 .Pp
 161 .It LOGIN_SETCPUMASK
 162 Create a new
 163 .Xr cpuset 2
 164 and set the cpu affinity to the specified mask.
 165 The string may contain a comma separated list of numbers and/or number
 166 ranges as handled by the
 167 .Xr cpuset 1
 168 utility or the case-insensitive string
 169 .Ql default .
 170 If the string is
 171 .Ql default
 172 no action will be taken.
 173 .It LOGIN_SETALL
 174 Enables all of the above settings.
 175 .El
 176 .Pp
 177 Note that when setting environment variables and a valid passwd
 178 pointer is provided in the
 179 .Ar pwd
 180 parameter, the characters
 181 .Ql \&~
 182 and
 183 .Ql \&$
 184 are substituted for the user's home directory and login name
 185 respectively.
 186 .Pp
 187 The
 188 .Fn setclasscpumask ,
 189 .Fn setclassresources
 190 and
 191 .Fn setclassenvironment
 192 functions are subsets of the setcontext functions above, but may
 193 be useful in isolation.
 194 .Sh RETURN VALUES
 195 The
 196 .Fn setclasscontext
 197 and
 198 .Fn setusercontext
 199 functions return -1 if an error occurred, or 0 on success.
 200 If an error occurs when attempting to set the user, login, group
 201 or resources, a message is reported to
 202 .Xr syslog 3 ,
 203 with LOG_ERR priority and directed to the currently active facility.
 204 .Sh SEE ALSO
 205 .Xr cpuset 1 ,
 206 .Xr cpuset 2 ,
 207 .Xr setgid 2 ,
 208 .Xr setlogin 2 ,
 209 .Xr setuid 2 ,
 210 .Xr getcap 3 ,
 211 .Xr initgroups 3 ,
 212 .Xr login_cap 3 ,
 213 .Xr mac_set_proc 3 ,
 214 .Xr login.conf 5 ,
 215 .Xr termcap 5