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: src/lib/libutil/login_class.3,v 1.9.2.4 2003/04/29 14:40:07 trhodes Exp $
  21 .\"
  22 .Dd December 28, 1996
  23 .Dt LOGIN_CLASS 3
  24 .Os
  25 .Sh NAME
  26 .Nm setclasscontext ,
  27 .Nm setclassenvironment ,
  28 .Nm setclassresources ,
  29 .Nm setusercontext
  30 .Nd "functions for using the login class capabilities database"
  31 .Sh LIBRARY
  32 .Lb libutil
  33 .Sh SYNOPSIS
  34 .In sys/types.h
  35 .In login_cap.h
  36 .Ft int
  37 .Fn setclasscontext "const char *classname" "unsigned int flags"
  38 .Ft int
  39 .Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
  40 .Ft void
  41 .Fn setclassresources "login_cap_t *lc"
  42 .Ft void
  43 .Fn setclassenvironment "login_cap_t *lc" "const struct passwd *pwd" "int paths"
  44 .Sh DESCRIPTION
  45 These functions provide a higher level interface to the login class
  46 database than those documented in
  47 .Xr login_cap 3 .
  48 These functions are used to set resource limits, environment and
  49 accounting settings for users on logging into the system and when
  50 selecting an appropriate set of environment and resource settings
  51 for system daemons based on login classes.
  52 These functions may only be called if the current process is
  53 running with root privileges.
  54 If the
  55 .Dv LOGIN_SETLOGIN
  56 flag is used this function calls
  57 .Xr setlogin 2 ,
  58 and due care must be taken as detailed in the manpage for that
  59 function and this affects all processes running in the same session
  60 and not just the current process.
  61 .Pp
  62 .Fn setclasscontext
  63 sets various class context values (resource limits, umask and
  64 process priorities) based on values for a specific named class.
  65 .Pp
  66 The function
  67 .Fn setusercontext
  68 sets class context values based on a given login_cap_t
  69 object, a specific passwd record (if login_cap_t is NULL),
  70 sets the current session's login and the current process
  71 user and group ownership.
  72 Each of these functions 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 ".Dv LOGIN_SETRESOURCES"
  77 .It Dv LOGIN_SETLOGIN
  78 Set the login associated with the current session to the user
  79 specified in the passwd structure.
  80 .Xr setlogin 2 .
  81 The
  82 .Ar pwd
  83 parameter must not be NULL if this option is used.
  84 .It Dv 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 Dv 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 Dv 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 .Ed
 118 .It Dv LOGIN_SETPRIORITY
 119 Set the scheduling priority for the current process based on the
 120 value specified in the system login class database.
 121 Class capability tags used:
 122 .Bd -literal
 123 priority
 124 .Ed
 125 .It Dv LOGIN_SETUMASK
 126 Set the umask for the current process to a value in the user or
 127 system login class database.
 128 Class capability tags used:
 129 .Bd -literal
 130 umask
 131 .Ed
 132 .It Dv LOGIN_SETPATH
 133 Set the "path" and "manpath" environment variables based on values
 134 in the user or system login class database.
 135 Class capability tags used with the corresponding environment
 136 variables set:
 137 .Bd -literal
 138 path          PATH
 139 manpath       MANPATH
 140 .Ed
 141 .It Dv LOGIN_SETENV
 142 Set various environment variables based on values in the user or
 143 system login class database.
 144 Class capability tags used with the corresponding environment
 145 variables set:
 146 .Bd -literal
 147 lang          LANG
 148 charset       MM_CHARSET
 149 timezone      TZ
 150 term          TERM
 151 .Ed
 152 .Pp
 153 Additional environment variables may be set using the list type
 154 capability "setenv=var1 val1,var2 val2..,varN valN".
 155 .It Dv LOGIN_SETALL
 156 Enables all of the above settings.
 157 .El
 158 .Pp
 159 Note that when setting environment variables and a valid passwd
 160 pointer is provided in the
 161 .Ar pwd
 162 parameter, the characters
 163 .Ql \&~
 164 and
 165 .Ql \&$
 166 are substituted for the user's home directory and login name
 167 respectively.
 168 .Pp
 169 The
 170 .Fn setclassresources
 171 and
 172 .Fn setclassenvironment
 173 functions are subsets of the setcontext functions above, but may
 174 be useful in isolation.
 175 .Sh RETURN VALUES
 176 The
 177 .Fn setclasscontext
 178 and
 179 .Fn setusercontext
 180 functions return -1 if an error occurred, or 0 on success.
 181 If an error occurs when attempting to set the user, login, group
 182 or resources, a message is reported to
 183 .Xr syslog 3 ,
 184 with
 185 .Dv LOG_ERR
 186 priority and directed to the currently active facility.
 187 .Sh ERRORS
 188 .Bl -tag -width Er
 189 .It Bq Er ENOMEM
 190 The function
 191 .Fn setclassenvironment
 192 failed because it were unable to allocate memory for the environment.
 193 .El
 194 .Sh SEE ALSO
 195 .Xr setgid 2 ,
 196 .Xr setlogin 2 ,
 197 .Xr setuid 2 ,
 198 .Xr getcap 3 ,
 199 .Xr initgroups 3 ,
 200 .Xr login_cap 3 ,
 201 .Xr login.conf 5 ,
 202 .Xr termcap 5