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