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