eaa2026406f52e36c7534d77b88791a73af484ef
[util-vserver.git] / util-vserver / lib / vserver.h
1 /* $Id$
2
3 *  Copyright (C) 2003 Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>
4 *   
5 *  This program is free software; you can redistribute it and/or modify
6 *  it under the terms of the GNU General Public License as published by
7 *  the Free Software Foundation; either version 2, or (at your option)
8 *  any later version.
9 *   
10 *  This program is distributed in the hope that it will be useful,
11 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 *  GNU General Public License for more details.
14 *   
15 *  You should have received a copy of the GNU General Public License
16 *  along with this program; if not, write to the Free Software
17 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
18 */
19
20 /** \file vserver.h
21  *  \brief The public interface of the the libvserver library.
22  */
23
24 #ifndef H_VSERVER_SYSCALL_H
25 #define H_VSERVER_SYSCALL_H
26
27 #include <stdint.h>
28 #include <stdlib.h>
29 #include <stdbool.h>
30 #include <sys/types.h>
31
32 #ifndef IS_DOXYGEN
33 #if defined(__GNUC__)
34 #  define VC_ATTR_UNUSED                __attribute__((__unused__))
35 #  define VC_ATTR_NORETURN              __attribute__((__noreturn__))
36 #  define VC_ATTR_CONST                 __attribute__((__const__))
37 #  define VC_ATTR_DEPRECATED            __attribute__((__deprecated__))
38 #  if __GNUC__*0x10000 + __GNUC_MINOR__*0x100 + __GNUC_PATCHLEVEL__ >= 0x30300
39 #    define VC_ATTR_NONNULL(ARGS)       __attribute__((__nonnull__ ARGS))
40 #    define VC_ATTR_ALWAYSINLINE        __attribute__((__always_inline__))
41 #  else
42 #    define VC_ATTR_NONNULL(ARGS)
43 #    define VC_ATTR_ALWAYSINLINE
44 #  endif
45 #  if __GNUC__*0x10000 + __GNUC_MINOR__*0x100 + __GNUC_PATCHLEVEL__ >= 0x30303
46 #    define VC_ATTR_PURE                __attribute__((__pure__))
47 #  else
48 #    define VC_ATTR_PURE
49 #  endif
50 #else
51 #  define VC_ATTR_NONNULL(ARGS)
52 #  define VC_ATTR_UNUSED
53 #  define VC_ATTR_NORETURN
54 #  define VC_ATTR_ALWAYSINLINE
55 #  define VC_ATTR_DEPRECATED
56 #  define VC_ATTR_PURE
57 #  define VC_ATTR_CONST
58 #endif
59 #endif  // IS_DOXYGEN
60
61 /** the value which is returned in error-case (no ctx found) */
62 #define VC_NOCTX                ((xid_t)(-1))
63 /** the value which means a random (the next free) ctx */
64 #define VC_DYNAMIC_XID          ((xid_t)(-1))
65 /** the value which means the current ctx */
66 #define VC_SAMECTX              ((xid_t)(-2))
67
68 #define VC_LIM_INFINITY         (~0ULL)
69 #define VC_LIM_KEEP             (~1ULL)
70
71   
72 #ifndef S_CTX_INFO_LOCK
73 #  define S_CTX_INFO_LOCK       1
74 #endif
75
76 #ifndef S_CTX_INFO_SCHED
77 #  define S_CTX_INFO_SCHED      2
78 #endif
79
80 #ifndef S_CTX_INFO_NPROC
81 #  define S_CTX_INFO_NPROC      4
82 #endif
83
84 #ifndef S_CTX_INFO_PRIVATE
85 #  define S_CTX_INFO_PRIVATE    8
86 #endif
87
88 #ifndef S_CTX_INFO_INIT
89 #  define S_CTX_INFO_INIT       16
90 #endif
91
92 #ifndef S_CTX_INFO_HIDEINFO
93 #  define S_CTX_INFO_HIDEINFO   32
94 #endif
95
96 #ifndef S_CTX_INFO_ULIMIT
97 #  define S_CTX_INFO_ULIMIT     64
98 #endif
99
100 #ifndef S_CTX_INFO_NAMESPACE
101 #  define S_CTX_INFO_NAMESPACE  128
102 #endif
103
104 #define VC_CAP_CHOWN                     0
105 #define VC_CAP_DAC_OVERRIDE              1
106 #define VC_CAP_DAC_READ_SEARCH           2
107 #define VC_CAP_FOWNER                    3
108 #define VC_CAP_FSETID                    4
109 #define VC_CAP_KILL                      5
110 #define VC_CAP_SETGID                    6
111 #define VC_CAP_SETUID                    7
112 #define VC_CAP_SETPCAP                   8
113 #define VC_CAP_LINUX_IMMUTABLE           9
114 #define VC_CAP_NET_BIND_SERVICE         10
115 #define VC_CAP_NET_BROADCAST            11
116 #define VC_CAP_NET_ADMIN                12
117 #define VC_CAP_NET_RAW                  13
118 #define VC_CAP_IPC_LOCK                 14
119 #define VC_CAP_IPC_OWNER                15
120 #define VC_CAP_SYS_MODULE               16
121 #define VC_CAP_SYS_RAWIO                17
122 #define VC_CAP_SYS_CHROOT               18
123 #define VC_CAP_SYS_PTRACE               19
124 #define VC_CAP_SYS_PACCT                20
125 #define VC_CAP_SYS_ADMIN                21
126 #define VC_CAP_SYS_BOOT                 22
127 #define VC_CAP_SYS_NICE                 23
128 #define VC_CAP_SYS_RESOURCE             24
129 #define VC_CAP_SYS_TIME                 25
130 #define VC_CAP_SYS_TTY_CONFIG           26
131 #define VC_CAP_MKNOD                    27
132 #define VC_CAP_LEASE                    28
133 #define VC_CAP_QUOTACTL                 29
134
135 #define VC_IMMUTABLE_FILE_FL            0x00000010l
136 #define VC_IMMUTABLE_LINK_FL            0x00008000l
137 #define VC_IMMUTABLE_ALL                (VC_IMMUTABLE_LINK_FL|VC_IMMUTABLE_FILE_FL)
138
139 #define VC_IATTR_XID                    0x01000000
140
141 #define VC_IATTR_ADMIN                  0x00000001
142 #define VC_IATTR_WATCH                  0x00000002
143 #define VC_IATTR_HIDE                   0x00000004
144 #define VC_IATTR_FLAGS                  0x00000007
145
146 #define VC_IATTR_BARRIER                0x00010000
147 #define VC_IATTR_IUNLINK                0x00020000
148 #define VC_IATTR_IMMUTABLE              0x00040000
149
150
151 // the flags
152 #define VC_VXF_INFO_LOCK                0x00000001
153 #define VC_VXF_INFO_NPROC               0x00000004
154 #define VC_VXF_INFO_PRIVATE             0x00000008
155 #define VC_VXF_INFO_INIT                0x00000010
156
157 #define VC_VXF_INFO_HIDEINFO            0x00000020
158 #define VC_VXF_INFO_ULIMIT              0x00000040
159 #define VC_VXF_INFO_NAMESPACE           0x00000080
160
161 #define VC_VXF_SCHED_HARD               0x00000100
162 #define VC_VXF_SCHED_PRIO               0x00000200
163 #define VC_VXF_SCHED_PAUSE              0x00000400
164
165 #define VC_VXF_VIRT_MEM                 0x00010000
166 #define VC_VXF_VIRT_UPTIME              0x00020000
167 #define VC_VXF_VIRT_CPU                 0x00040000
168
169 #define VC_VXF_HIDE_MOUNT               0x01000000
170 #define VC_VXF_HIDE_NETIF               0x02000000
171
172 #define VC_VXF_STATE_SETUP              (1ULL<<32)
173 #define VC_VXF_STATE_INIT               (1ULL<<33)
174
175 // the ccapabilities
176 #define VC_VXC_SET_UTSNAME              0x00000001
177 #define VC_VXC_SET_RLIMIT               0x00000002
178
179 #define VC_VXC_ICMP_PING                0x00000100
180
181 #define VC_VXC_SECURE_MOUNT             0x00010000
182
183
184 /** \defgroup  syscalls Syscall wrappers
185  *  Functions which are calling the vserver syscall directly. */
186
187 /** \defgroup  helper   Helper functions
188  *  Functions which are doing general helper tasks like parameter parsing. */
189
190 /** \typedef  an_unsigned_integer_type  xid_t
191  *  The identifier of a context. */
192
193 #ifdef IS_DOXYGEN
194 typedef an_unsigned_integer_type        xid_t;
195 #endif
196
197 #ifdef __cplusplus
198 extern "C" {
199 #endif
200
201   struct vc_ip_mask_pair {
202     uint32_t    ip;
203       uint32_t  mask;
204   };
205
206     /** \brief   Returns the version of the current kernel API.
207      *  \ingroup syscalls
208      *  \returns The versionnumber of the kernel API
209      */
210   int   vc_get_version();
211   
212     /** \brief   Moves current process into a context
213      *  \ingroup syscalls
214      *
215      *  Puts current process into context \a ctx, removes the capabilities
216      *  given in \a remove_cap and sets \a flags.
217      *
218      *  \param ctx         The new context; special values for are
219      *  - VC_SAMECTX      which means the current context (just for changing caps and flags)
220      *  - VC_DYNAMIC_XID  which means the next free context; this value can be used by
221      *                    ordinary users also
222      *  \param remove_cap  The linux capabilities which will be \b removed.
223      *  \param flags       Special flags which will be set.
224      *
225      *  \returns  The new context-id, or VC_NOCTX on errors; errno
226      *            will be set appropriately
227      *
228      *  See http://vserver.13thfloor.at/Stuff/Logic.txt for details */
229   xid_t vc_new_s_context(xid_t ctx, unsigned int remove_cap, unsigned int flags);
230
231     /** \brief  Sets the ipv4root information.
232      *  \ingroup syscalls
233      *  \pre    \a nb < NB_IPV4ROOT && \a ips != 0 */
234   int   vc_set_ipv4root(uint32_t  bcast, size_t nb,
235                         struct vc_ip_mask_pair const *ips) VC_ATTR_NONNULL((3));
236
237     /** \brief  Returns the value of NB_IPV4ROOT.
238      *  \ingroup helper
239      *
240      *  This function returns the value of NB_IPV4ROOT which was used when the
241      *  library was built, but \b not the value which is used by the currently
242      *  running kernel. */
243   size_t        vc_get_nb_ipv4root() VC_ATTR_CONST VC_ATTR_PURE;
244
245     /** \brief   Creates a context without starting it.
246      *  \ingroup syscalls
247      *
248      *  This functions initializes a new context. When already in a freshly
249      *  created context, this old context will be discarded.
250      *
251      *  \param xid  The new context; special values are:
252      *  - VC_DYNAMIC_XID which means to create a dynamic context
253      *
254      *  \returns the xid of the created context, or VC_NOCTX on errors. errno
255      *           will be set appropriately. */
256   xid_t vc_ctx_create(xid_t xid);
257
258     /** \brief   Moves the current process into the specified context.
259      *  \ingroup syscalls
260      *
261      *  \param   xid  The new context
262      *  \returns 0 on success, -1 on errors */
263   int   vc_ctx_migrate(xid_t xid);
264   
265     /* rlimit related functions */
266   
267     /** \brief  The type which is used for a single limit value.
268      *
269      *  Special values are
270      *  - VC_LIM_INFINITY ... which is the infinite value
271      *  - VC_LIM_KEEP     ... which is used to mark values which shall not be
272      *                        modified by the vc_set_rlimit() operation.
273      *
274      *  Else, the interpretation of the value depends on the corresponding
275      *  resource; it might be bytes, pages, seconds or litres of beer. */
276   typedef uint_least64_t        vc_limit_t;
277
278     /** \brief  The limits of a resources.
279      *
280      *  This is a triple consisting of a minimum, soft and hardlimit. */
281   struct vc_rlimit {
282       vc_limit_t        min;    ///< the guaranted minimum of a resources
283       vc_limit_t        soft;   ///< the softlimit of a resource
284       vc_limit_t        hard;   ///< the absolute hardlimit of a resource
285   };
286
287     /** \brief  Masks describing the supported limits. */
288   struct  vc_rlimit_mask {
289       uint_least32_t    min;    ///< masks the resources supporting a minimum limit
290       uint_least32_t    soft;   ///< masks the resources supporting a soft limit
291       uint_least32_t    hard;   ///< masks the resources supporting a hard limit
292   };
293
294     /** \brief   Returns the limits of \a resource.
295      *  \ingroup syscalls
296      *
297      *  \param  xid       The id of the context
298      *  \param  resource  The resource which will be queried
299      *  \param  lim       The result which will be filled with the limits
300      *
301      *  \returns 0 on success, and -1 on errors. */
302   int   vc_get_rlimit(xid_t xid, int resource,
303                       struct vc_rlimit       /*@out@*/ *lim) VC_ATTR_NONNULL((3));
304     /** \brief   Sets the limits of \a resource.
305      *  \ingroup syscalls
306      *
307      *  \param  xid       The id of the context
308      *  \param  resource  The resource which will be queried
309      *  \param  lim       The new limits
310      *
311      *  \returns 0 on success, and -1 on errors. */
312   int   vc_set_rlimit(xid_t xid, int resource,
313                       struct vc_rlimit const /*@in@*/  *lim) VC_ATTR_NONNULL((3));
314   int   vc_get_rlimit_mask(xid_t xid,
315                            struct vc_rlimit_mask *lim)       VC_ATTR_NONNULL((2));
316     /** \brief   Parses a string describing a limit
317      *  \ingroup helper
318      *
319      *  This function parses \a str and interprets special words like \p "inf"
320      *  or suffixes. Valid suffixes are
321      *  - \p k ... 1000
322      *  - \p m ... 1000000
323      *  - \p K ... 1024
324      *  - \p M ... 1048576
325      *
326      *  \param str  The string which shall be parsed
327      *  \param res  Will be filled with the interpreted value; in errorcase,
328      *              this value is undefined.
329      *
330      *  \returns \a true, iff the string \a str could be parsed. \a res will
331      *  be filled with the interpreted value in this case. 
332      *
333      *  \pre \a str!=0 && \a res!=0
334      */
335   bool  vc_parseLimit(char const /*@in@*/ *str, vc_limit_t /*@out@*/ *res)      VC_ATTR_NONNULL((1,2));
336
337
338   /** \brief    Sends a signal to a context/pid
339    *  \ingroup  syscalls
340    *
341    *  Special values for \a pid are:
342    *  - -1   which means every process in ctx except the init-process
343    *  -  0   which means every process in ctx inclusive the init-process */
344   int   vc_ctx_kill(xid_t ctx, pid_t pid, int sig);
345
346
347
348   int           vc_set_iattr(char const *filename, xid_t xid,
349                              uint_least32_t flags, uint_least32_t mask) VC_ATTR_NONNULL((1));
350   int           vc_get_iattr(char const *filename, xid_t * /*@null@*/ xid,
351                              uint_least32_t * /*@null@*/ flags,
352                              uint_least32_t * /*@null@*/ mask) VC_ATTR_NONNULL((1));
353
354   struct vc_vx_info {
355       xid_t     xid;
356       pid_t     initpid;
357   };
358   
359     /** Returns the context of the given process. pid==0 means the current process. */
360   xid_t         vc_get_task_xid(pid_t pid);
361   int           vc_get_vx_info(xid_t xid, struct vc_vx_info *info) VC_ATTR_NONNULL((2));
362
363
364   typedef enum { vcVHI_CONTEXT, vcVHI_SYSNAME, vcVHI_NODENAME,
365                  vcVHI_RELEASE, vcVHI_VERSION, vcVHI_MACHINE,
366                  vcVHI_DOMAINNAME }             vc_uts_type;
367   
368   int           vc_set_vhi_name(xid_t xid, vc_uts_type type,
369                                 char const *val, size_t len) VC_ATTR_NONNULL((3));
370   int           vc_get_vhi_name(xid_t xid, vc_uts_type type,
371                                 char *val, size_t len)       VC_ATTR_NONNULL((3));
372
373     /** Returns true iff \a xid is a dynamic xid */
374   bool          vc_is_dynamic_xid(xid_t xid);
375
376   int           vc_enter_namespace(xid_t xid);
377   int           vc_set_namespace();
378   int           vc_cleanup_namespace();
379
380   struct  vc_ctx_flags {
381       uint_least64_t    flagword;
382       uint_least64_t    mask;
383   };
384   
385   struct  vc_ctx_caps {
386       uint_least64_t    bcaps;
387       uint_least64_t    bmask;
388       uint_least64_t    ccaps;
389       uint_least64_t    cmask;
390   };
391
392   struct vc_err_listparser {
393       char const        *ptr;
394       size_t            len;
395   };
396  
397   int                   vc_get_cflags(xid_t xid, struct vc_ctx_flags *)       VC_ATTR_NONNULL((2));
398   int                   vc_set_cflags(xid_t xid, struct vc_ctx_flags const *) VC_ATTR_NONNULL((2));
399
400   int                   vc_get_ccaps(xid_t xid, struct vc_ctx_caps *);
401   int                   vc_set_ccaps(xid_t xid, struct vc_ctx_caps const *);
402
403   uint_least64_t        vc_text2bcap(char const *, size_t len);
404   char const *          vc_lobcap2text(uint_least64_t *);
405   int                   vc_list2bcap(char const *, size_t len,
406                                      struct vc_err_listparser *err,
407                                      struct vc_ctx_caps *);
408
409   uint_least64_t        vc_text2ccap(char const *, size_t len);
410   char const *          vc_loccap2text(uint_least64_t *);
411   int                   vc_list2ccap(char const *, size_t len,
412                                      struct vc_err_listparser *err,
413                                      struct vc_ctx_caps *);
414
415   int                   vc_list2cflag(char const *, size_t len,
416                                      struct vc_err_listparser *err,
417                                      struct vc_ctx_flags *flags);
418   uint_least64_t        vc_text2cflag(char const *, size_t len);
419   char const *          vc_locflag2text(uint_least64_t *);
420   
421   uint_least32_t        vc_list2cflag_compat(char const *, size_t len,
422                                             struct vc_err_listparser *err);
423   uint_least32_t        vc_text2cflag_compat(char const *, size_t len);
424   char const *          vc_hicflag2text_compat(uint_least32_t);
425
426   uint_least32_t        vc_get_insecurecaps() VC_ATTR_CONST;
427   int                   vc_text2cap(char const *);
428   char const *          vc_cap2text(unsigned int);
429
430
431   inline static int     vc_setfilecontext(char const *filename, xid_t xid) {
432     return vc_set_iattr(filename, xid, 0, VC_IATTR_XID);
433   }
434   
435   inline static xid_t   vc_getfilecontext(char const *filename) {
436     xid_t       res;
437     if (vc_get_iattr(filename, &res, 0,0)==-1) return VC_NOCTX;
438     return res;
439   }
440
441
442   struct vc_set_sched {
443       int32_t   fill_rate;
444       int32_t   interval;
445       int32_t   tokens;
446       int32_t   tokens_min;
447       int32_t   tokens_max;
448       uint64_t  cpu_mask;
449   };
450
451   int           vc_set_sched(xid_t xid, struct vc_set_sched const *);
452   
453   
454   typedef enum { vcFEATURE_VKILL,  vcFEATURE_IATTR,   vcFEATURE_RLIMIT,
455                  vcFEATURE_COMPAT, vcFEATURE_MIGRATE, vcFEATURE_NAMESPACE,
456                  vcFEATURE_SCHED,  vcFEATURE_VINFO,   vcFEATURE_VHI,
457                  vcFEATURE_VSHELPER0, vcFEATURE_VSHELPER }
458     vcFeatureSet;
459
460   bool          vc_isSupported(vcFeatureSet) VC_ATTR_CONST;
461   bool          vc_isSupportedString(char const *);
462
463   /* The management part */
464
465 #define VC_LIMIT_VSERVER_NAME_LEN       1024
466   
467   typedef enum { vcCFG_NONE, vcCFG_AUTO,
468                  vcCFG_LEGACY,
469                  vcCFG_RECENT_SHORT,
470                  vcCFG_RECENT_FULL }            vcCfgStyle;
471
472
473   /** Maps an xid given at '--xid' options to an xid_t */
474   xid_t         vc_xidopt2xid(char const *, bool honor_static, char const **err_info);
475
476   vcCfgStyle    vc_getVserverCfgStyle(char const *id);
477   
478   /** Resolves the name of the vserver. The result will be allocated and must
479       be freed by the caller. */
480   char *        vc_getVserverName(char const *id, vcCfgStyle style);
481
482   /** Returns the path of the vserver configuration directory. When the given
483    *  vserver does not exist, or when it does not have such a directory, NULL
484    *  will be returned. Else, the result will be allocated and must be freed
485    *  by the caller. */
486   char *        vc_getVserverCfgDir(char const *id, vcCfgStyle style);
487
488   /** Returns the path of the configuration directory for the given
489    *  application. The result will be allocated and must be freed by the
490    *  caller. */
491   char *        vc_getVserverAppDir(char const *id, vcCfgStyle style, char const *app);
492
493   /** Returns the path to the vserver root-directory. The result will be
494    *  allocated and must be freed by the caller. */
495   char *        vc_getVserverVdir(char const *id, vcCfgStyle style, bool physical);
496
497   /** Returns the ctx of the given vserver. When vserver is not running and
498    *  'honor_static' is false, VC_NOCTX will be returned. Else, when
499    *  'honor_static' is true and a static assignment exists, those value will
500    *  be returned. Else, the result will be VC_NOCTX.
501    *
502    *  When 'is_running' is not null, the status of the vserver will be
503    *  assigned to this variable. */
504   xid_t         vc_getVserverCtx(char const *id, vcCfgStyle style,
505                                  bool honor_static, bool /*@null@*/ *is_running);
506
507   /** Resolves the cfg-path of the vserver owning the given ctx. 'revdir' will
508       be used as the directory holding the mapping-links; when NULL, the
509       default value will be assumed.  The result will be allocated and must be
510       freed by the caller. */
511   char *        vc_getVserverByCtx(xid_t ctx, /*@null@*/vcCfgStyle *style,
512                                    /*@null@*/char const *revdir);
513
514 #define vcSKEL_INTERFACES       1u
515 #define vcSKEL_PKGMGMT          2u
516 #define vcSKEL_FILESYSTEM       4u
517   
518   /** Create a basic configuration skeleton for a vserver plus toplevel
519    *  directories for pkgmanagemt and filesystem (when requested). */
520   int           vc_createSkeleton(char const *id, vcCfgStyle style, int flags);
521   
522 #ifdef __cplusplus
523 }
524 #endif
525
526 #undef VC_ATTR_PURE
527 #undef VC_ATTR_ALWAYSINLINE
528 #undef VC_ATTR_NORETURN
529 #undef VC_ATTR_UNUSED
530 #undef VC_ATTR_NONNULL
531
532 #endif