src/lxc/terminal.h

   1 /*
   2  * lxc: linux Container library
   3  *
   4  * (C) Copyright IBM Corp. 2007, 2010
   5  *
   6  * Authors:
   7  * Daniel Lezcano <daniel.lezcano at free.fr>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  22  */
  23
  24 #ifndef __LXC_CONSOLE_H
  25 #define __LXC_CONSOLE_H
  26
  27 #include "config.h"
  28
  29 #include <signal.h>
  30 #include <stdio.h>
  31
  32 #include "list.h"
  33 #include "ringbuf.h"
  34
  35 struct lxc_container;
  36 struct lxc_conf;
  37 struct lxc_epoll_descr;
  38
  39 /* Defines a structure containing a pty information for virtualizing a tty
  40  * @name   : the path name of the slave pty side
  41  * @master : the file descriptor of the master
  42  * @slave  : the file descriptor of the slave
  43  */
  44 struct lxc_terminal_info {
  45         char name[MAXPATHLEN];
  46         int master;
  47         int slave;
  48         int busy;
  49 };
  50
  51 struct lxc_terminal_state {
  52         struct lxc_list node;
  53         int stdinfd;
  54         int stdoutfd;
  55         int masterfd;
  56         /* Escape sequence to use for exiting the pty. A single char can be
  57          * specified. The pty can then exited by doing: Ctrl + specified_char +
  58          * q. This field is checked by lxc_terminal_stdin_cb(). Set to -1 to
  59          * disable exiting the pty via a escape sequence.
  60          */
  61         int escape;
  62         /* Used internally by lxc_terminal_stdin_cb() to check whether an
  63          * escape sequence has been received.
  64          */
  65         int saw_escape;
  66         /* Name of the container to forward the SIGWINCH event to. */
  67         const char *winch_proxy;
  68         /* Path of the container to forward the SIGWINCH event to. */
  69         const char *winch_proxy_lxcpath;
  70         /* File descriptor that accepts signals. If set to -1 no signal handler
  71          * could be installed. This also means that the sigset_t oldmask member
  72          * is meaningless.
  73          */
  74         int sigfd;
  75         sigset_t oldmask;
  76 };
  77
  78 struct lxc_terminal {
  79         int slave;
  80         int master;
  81         int peer;
  82         struct lxc_terminal_info proxy;
  83         struct lxc_epoll_descr *descr;
  84         char *path;
  85         char name[MAXPATHLEN];
  86         struct termios *tios;
  87         struct lxc_terminal_state *tty_state;
  88
  89         struct /* lxc_console_log */ {
  90                 /* size of the log file */
  91                 uint64_t log_size;
  92
  93                 /* path to the log file */
  94                 char *log_path;
  95
  96                 /* fd to the log file */
  97                 int log_fd;
  98
  99                 /* whether the log file will be rotated */
 100                 unsigned int log_rotate;
 101         };
 102
 103         struct /* lxc_terminal_ringbuf */ {
 104                 /* size of the ringbuffer */
 105                 uint64_t buffer_size;
 106
 107                 /* the in-memory ringbuffer */
 108                 struct lxc_ringbuf ringbuf;
 109         };
 110 };
 111
 112 /*
 113  * lxc_terminal_allocate: allocate the console or a tty
 114  *
 115  * @conf    : the configuration of the container to allocate from
 116  * @sockfd  : the socket fd whose remote side when closed, will be an
 117  *            indication that the console or tty is no longer in use
 118  * @ttyreq  : the tty requested to be opened, -1 for any, 0 for the console
 119  */
 120 extern int  lxc_terminal_allocate(struct lxc_conf *conf, int sockfd, int *ttynum);
 121
 122 /*
 123  * Create a new pty:
 124  * - calls openpty() to allocate a master/slave pty pair
 125  * - sets the FD_CLOEXEC flag on the master/slave fds
 126  * - allocates either the current controlling pty (default) or a user specified
 127  *   pty as peer pty for the newly created master/slave pair
 128  * - sets up SIGWINCH handler, winsz, and new terminal settings
 129  *   (Handlers for SIGWINCH and I/O are not registered in a mainloop.)
 130  * (For an unprivileged container the created pty on the host is not
 131  * automatically chowned to the uid/gid of the unprivileged user. For this
 132  * ttys_shift_ids() can be called.)
 133  */
 134 extern int lxc_terminal_create(struct lxc_terminal *console);
 135
 136 /**
 137  * lxc_terminal_setup: Create a new pty.
 138  * - In addition to lxc_terminal_create() also sets up all pty logs.
 139  */
 140 extern int lxc_terminal_setup(struct lxc_conf *);
 141
 142 /*
 143  * Delete a pty created via lxc_terminal_setup():
 144  * - set old terminal settings
 145  * - memory allocated via lxc_terminal_setup() is free()ed.
 146  * - close master/slave pty pair and allocated fd for the peer (usually
 147  *   /dev/tty)
 148  * Registered handlers in a mainloop are not automatically deleted.
 149  */
 150 extern void lxc_terminal_delete(struct lxc_terminal *);
 151
 152 /*
 153  * lxc_terminal_free: mark the console or a tty as unallocated, free any
 154  * resources allocated by lxc_terminal_allocate().
 155  *
 156  * @conf : the configuration of the container whose tty was closed
 157  * @fd   : the socket fd whose remote side was closed, which indicated
 158  *         the console or tty is no longer in use. this is used to match
 159  *         which console/tty is being freed.
 160  */
 161 extern void lxc_terminal_free(struct lxc_conf *conf, int fd);
 162
 163 /*
 164  * Register pty event handlers in an open mainloop
 165  */
 166 extern int  lxc_terminal_mainloop_add(struct lxc_epoll_descr *, struct lxc_terminal *);
 167
 168 /*
 169  * Handle SIGWINCH events on the allocated ptys.
 170  */
 171 extern void lxc_terminal_sigwinch(int sig);
 172
 173 /*
 174  * Connect to one of the ptys given to the container via lxc.tty.max.
 175  * - allocates either the current controlling pty (default) or a user specified
 176  *   pty as peer pty for the containers tty
 177  * - sets up SIGWINCH handler, winsz, and new terminal settings
 178  * - opens mainloop
 179  * - registers SIGWINCH, I/O handlers in the mainloop
 180  * - performs all necessary cleanup operations
 181  */
 182 extern int  lxc_console(struct lxc_container *c, int ttynum,
 183                         int stdinfd, int stdoutfd, int stderrfd,
 184                         int escape);
 185
 186 /*
 187  * Allocate one of the ptys given to the container via lxc.tty.max. Returns an
 188  * open fd to the allocated pty.
 189  * Set ttynum to -1 to allocate the first available pty, or to a value within
 190  * the range specified by lxc.tty.max to allocate a specific pty.
 191  */
 192 extern int  lxc_terminal_getfd(struct lxc_container *c, int *ttynum,
 193                               int *masterfd);
 194
 195 /*
 196  * Make fd a duplicate of the standard file descriptors:
 197  * fd is made a duplicate of a specific standard file descriptor iff the
 198  * standard file descriptor refers to a pty.
 199  */
 200 extern int lxc_terminal_set_stdfds(int fd);
 201
 202 /*
 203  * Handler for events on the stdin fd of the pty. To be registered via the
 204  * corresponding functions declared and defined in mainloop.{c,h} or
 205  * lxc_terminal_mainloop_add().
 206  * This function exits the loop cleanly when an EPOLLHUP event is received.
 207  */
 208 extern int lxc_terminal_stdin_cb(int fd, uint32_t events, void *cbdata,
 209                                  struct lxc_epoll_descr *descr);
 210
 211 /*
 212  * Handler for events on the master fd of the pty. To be registered via the
 213  * corresponding functions declared and defined in mainloop.{c,h} or
 214  * lxc_terminal_mainloop_add().
 215  * This function exits the loop cleanly when an EPOLLHUP event is received.
 216  */
 217 extern int lxc_terminal_master_cb(int fd, uint32_t events, void *cbdata,
 218                                   struct lxc_epoll_descr *descr);
 219
 220 /*
 221  * Setup new terminal properties. The old terminal settings are stored in
 222  * oldtios.
 223  */
 224 extern int lxc_setup_tios(int fd, struct termios *oldtios);
 225
 226
 227 /*
 228  * lxc_terminal_winsz: propagate winsz from one terminal to another
 229  *
 230  * @srcfd : terminal to get size from (typically a slave pty)
 231  * @dstfd : terminal to set size on (typically a master pty)
 232  */
 233 extern void lxc_terminal_winsz(int srcfd, int dstfd);
 234
 235 /*
 236  * lxc_terminal_signal_init: install signal handler
 237  *
 238  * @srcfd  : src for winsz in SIGWINCH handler
 239  * @dstfd  : dst for winsz in SIGWINCH handler
 240  *
 241  * Returns lxc_terminal_state structure on success or NULL on failure. The sigfd
 242  * member of the returned lxc_terminal_state can be select()/poll()ed/epoll()ed
 243  * on (ie added to a mainloop) for signals.
 244  *
 245  * Must be called with process_lock held to protect the lxc_ttys list, or
 246  * from a non-threaded context.
 247  *
 248  * Note that the signal handler isn't installed as a classic asychronous
 249  * handler, rather signalfd(2) is used so that we can handle the signal when
 250  * we're ready for it. This avoids deadlocks since a signal handler (ie
 251  * lxc_terminal_sigwinch()) would need to take the thread mutex to prevent
 252  * lxc_ttys list corruption, but using the fd we can provide the tty_state
 253  * needed to the callback (lxc_terminal_signalfd_cb()).
 254  *
 255  * This function allocates memory. It is up to the caller to free it.
 256  */
 257 extern struct lxc_terminal_state *lxc_terminal_signal_init(int srcfd, int dstfd);
 258
 259 /*
 260  * Handler for signal events. To be registered via the corresponding functions
 261  * declared and defined in mainloop.{c,h} or lxc_terminal_mainloop_add().
 262  */
 263 extern int lxc_terminal_signalfd_cb(int fd, uint32_t events, void *cbdata,
 264                                     struct lxc_epoll_descr *descr);
 265
 266 /*
 267  * lxc_terminal_signal_fini: uninstall signal handler
 268  *
 269  * @ts  : the lxc_terminal_state returned by lxc_terminal_signal_init
 270  *
 271  * Restore the saved signal handler that was in effect at the time
 272  * lxc_terminal_signal_init() was called.
 273  *
 274  * Must be called with process_lock held to protect the lxc_ttys list, or
 275  * from a non-threaded context.
 276  */
 277 extern void lxc_terminal_signal_fini(struct lxc_terminal_state *ts);
 278
 279 extern int lxc_terminal_write_ringbuffer(struct lxc_terminal *console);
 280 extern int lxc_terminal_create_log_file(struct lxc_terminal *console);
 281 extern int lxc_terminal_io_cb(int fd, uint32_t events, void *data,
 282                               struct lxc_epoll_descr *descr);
 283
 284 extern int lxc_make_controlling_pty(int fd);
 285 extern int lxc_login_pty(int fd);
 286 extern void lxc_terminal_conf_free(struct lxc_terminal *console);
 287 extern void lxc_terminal_info_init(struct lxc_terminal_info *pty);
 288 extern void lxc_terminal_init(struct lxc_terminal *pty);
 289 extern int lxc_terminal_map_ids(struct lxc_conf *c, struct lxc_terminal *pty);
 290
 291 #endif