DEVELOPMENT

   1
   2 This file should help you to add new address types and address options to
   3 socat.
   4
   5 NOTE:
   6 socat will in future releases be split into a library "libxio" containing all
   7 the address stuff, useful also for many other purposes, and the socat main()
   8 and data shuffler. If you intend to perform major changes to the xio part and
   9 to publish them, please contact me before!
  10
  11
  12 ADDING A NEW ADDRESS TYPE:
  13
  14 * Create new files xio-newaddr.c and xio-newaddr.h
  15
  16 * Create a new record of struct addrdesc in xio-newaddr.c, with declaration in xio-newaddr.h.
  17
  18 * Make a new entry to addressnames[] in xioopen.c with the addresses main name
  19 and maybe with alias names. Keep this array ASCII sorted, without uppercase
  20 chars.
  21
  22 * config.h.in: #undef WITH_NEWADDR
  23
  24 * configure.in: Copy the disable part of, e.g., WITH_SOCKS4 and adapt it to
  25 NEWADDR
  26
  27 * In socat.c, add to socat_version
  28
  29 * Write a function xioopen_newaddr() in xio-newaddr.c, declaration in
  30 xio-newaddr.h
  31 Do not forget the following option processing calls:
  32 All groups: _xio_openlate()
  33 Group FD: applyopts_cloexec()
  34 Group NAMED: applyopts_file() for phases PREOPEN, OPEN, and FD
  35
  36 * Describe a tested example in file EXAMPLES, and maybe in the socat manpage
  37 source.
  38
  39 * Try to define a test for this address type in test.sh
  40
  41 * Update file CHANGES
  42
  43
  44 ADDING A NEW ADDRESS OPTION:
  45
  46 xioopen.c:
  47
  48 * If this option depends on a #define that is probably not available on all
  49 platforms, make all new code for this option dependent on the existence of this
  50 C header define:
  51 #ifdef PREFIX_NEWOPTION
  52 ...
  53 #endif
  54
  55 * Add an OPT_NEWOPTION to enum e_optcode in xioopts.h, preferably keeping
  56 alphabetic order
  57
  58 * Add a struct optdesc opt_newoption record in xio-newaddr.c and its
  59 declaration in xio-newaddr.h. The complete structure definition must be in one
  60 line without breaks for automatic docu extraction.
  61 Build the record from the following components:
  62 . A canonical default name (e.g. "newoption")
  63 . A short, preferable name (e.g. "newopt") or NULL
  64 . OPT_NEWOPTION (from enum e_optcode, see above)
  65 . A group membership that restricts appliance of the new option to matching
  66 address types (e.g., one of GROUP_ANY, GROUP_IP_TCP, GROUP_EXEC)
  67 . A phase specification that positions this option within address processing.
  68 Note that the function code can override this value.
  69 . A representation type for option arguments (e.g., TYPE_INT, TYPE_STRING etc.;
  70 use TYPE_BOOL if this option just triggers an action)
  71 . A function or action definition for applying this option. If it does not use
  72 one of the standard functions (open(), ioctl(), setsockopt()...), then use
  73 OFUNC_SPEC (specific).
  74
  75 * For the canonical name and all its aliases and abbreviations, add entries to
  76 the array optionnames in xioopts.c. KEEP STRICT ALPHABETIC (ASCII) ORDER!
  77 The entries must be embedded in an IF_... macro of their group for conditional
  78 compiling.
  79
  80 * For options using some predefined action (see OFUNC above), this might be
  81 enough - test the option and document it in xio.help!
  82 For OFUNC_SPEC, it might suffice to add another "case" to the OFUNC_SPEC branch
  83 in applyopts() in xioopts.c. If you need more special handling, you should try
  84 to understand the address specific functions and add your code there.
  85
  86 * If you use system or low level C library calls or library calls that might
  87 hang or induce problems, please invoke them with capitalized name; if no such
  88 name is defined, add an appropriate debug function to sycls.c, and a header
  89 entry and a wrapper "define" to sycls.h
  90
  91 * Update file CHANGES
  92
  93
  94 INFO ABOUT ADDRESS PHASES:
  95
  96 Each option entry has a field specifying a default phase for its application.
  97 Of course, the code that analyses and applies an address may override this
  98 default phase.
  99
 100 Depending on the type of address there are several major phase sequences:
 101
 102
 103 OPEN addresses:
 104
 105 PH_INIT         retrieving info from original state
 106 PH_EARLY        before any other processing
 107 PH_PREOPEN      before file creation/opening (not UNIX sockets)
 108 PH_OPEN         during file creation/opening (not UNIX sockets)
 109 PH_PASTOPEN     past file creation/opening (not UNIX sockets)
 110 PH_FD           soon after FD creation or identification
 111 PH_LATE         FD is ready, before start of data loop
 112 PH_LATE2        FD is ready, dropping privileges
 113
 114
 115 SOCKET addresses:
 116
 117 PH_INIT         retrieving info from original state
 118 PH_EARLY        before any other processing
 119 PH_PRESOCKET    before socket call
 120 PH_SOCKET       for socket call
 121 PH_PASTSOCKET   after socket call
 122 PH_FD           soon after FD creation or identification
 123 PH_PREBIND      before socket bind()
 124 PH_BIND         during socket bind()
 125 PH_PASTBIND     past socket bind()
 126 PH_PRECONNECT   before connect()
 127 PH_CONNECT      during connect()
 128 PH_PASTCONNECT  after connect()
 129 PH_CONNECTED    phase common with listen
 130 PH_LATE         FD is ready, before start of data loop
 131 PH_LATE2        FD is ready, dropping privileges
 132
 133
 134 SOCKET with LISTEN and ACCEPT:
 135
 136 PH_INIT         retrieving info from original state
 137 PH_EARLY        before any other processing
 138 PH_PRESOCKET    before socket call
 139 PH_SOCKET       for socket call
 140 PH_PREBIND      before socket bind()
 141 PH_BIND         during socket bind()
 142 PH_PASTBIND     past socket bind()
 143 PH_PRELISTEN    before listen()
 144 PH_LISTEN       during listen()
 145 PH_PASTLISTEN   after listen()
 146 PH_PREACCEPT    before accept()
 147 PH_ACCEPT       during accept()
 148 PH_PASTACCEPT   after accept()
 149 # and the following on the new FD:
 150 PH_FD           soon after FD creation or identification
 151 PH_PASTSOCKET   after socket call
 152 PH_CONNECTED    phase common with connect
 153 PH_PREFORK      before forking
 154 PH_FORK         during fork()
 155 PH_PASTFORK     after fork()
 156 PH_LATE         FD is ready, before start of data loop
 157 PH_LATE2        FD is ready, dropping privileges
 158
 159
 160 FD addresses:
 161
 162 PH_INIT         retrieving info from original state
 163 PH_EARLY        before any other processing
 164 PH_FD           soon after FD identification
 165 PH_LATE         FD is ready, before start of data loop
 166 PH_LATE2        FD is ready, dropping privileges
 167
 168
 169 EXEC addresses:
 170
 171 PH_INIT         retrieving info from original state
 172 PH_EARLY        before any other processing
 173 PH_PREBIGEN     before socketpair() pipe() openpty()
 174 PH_BIGEN        during socketpair() pipe() openpty()
 175 PH_PASTBIGEN    past socketpair() pipe() openpty()
 176 PH_PASTSOCKET   for socketpair()
 177 PH_FD           soon after FD creation or identification
 178 PH_PREFORK      before forking
 179 PH_FORK         during fork()
 180 PH_PASTFORK     after fork()
 181 PH_LATE         FD is ready, before start of data loop
 182 PH_LATE2        FD is ready, dropping privileges
 183 PH_PREEXEC      before exec() or system()
 184 PH_EXEC         during exec() or system()
 185
 186
 187 There are lots of semantic relations between group, phase, and func fields of
 188 an option.
 189
 190
 191 There exists something like an overall phase sequence:
 192 PH_INIT                                         # su-d.1
 193 PH_EARLY                                        # chroot-early
 194 PH_PREOPEN,     PH_OPEN,        PH_PASTOPEN     # (chroot before/after?)
 195 PH_PRESOCKET,   PH_SOCKET,      PH_PASTSOCKET   # (su after (root for raw)?)
 196 PH_PREBIGEN,    PH_BIGEN,       PH_PASTBIGEN    # (chroot before/after (/dev..)?)
 197 PH_FD
 198 PH_PREBIND,     PH_BIND,        PH_PASTBIND     # (su after(before?))
 199 PH_PRELISTEN,   PH_LISTEN,      PH_PASTLISTEN
 200 PH_PRECONNECT,  PH_CONNECT,     PH_PASTCONNECT  # (chroot before/after (AF_UNIX)?)
 201 PH_PREACCEPT,   PH_ACCEPT,      PH_PASTACCEPT
 202 PH_CONNECTED
 203 PH_PREFORK,     PH_FORK,        PH_PASTFORK     # (all before/after?)
 204 PH_LATE                                         # chroot
 205 PH_LATE2                                        # su, su-d.2
 206 PH_PREEXEC,     PH_EXEC                         # (all before)
 207
 208 ===============================================================================
 209 // Up to 1.7.2.4 socat used non async signal safe system and library calls in signal handlers, mostly for logging purposes. This problem was fixed in release 1.7.3.0 with the following concepts:
 210
 211 Signal handlers set on entry and unset on return the diag_in_handler global variable. The logging system, when this variable is set, queues the text message together with errno and exit info in a UNIX datagram socket. When invoked with unset diag_in_handler it first checks if there are messages in that queue and prints them first.
 212
 213 A async signal safe but minimal version of vsnprintf, named vsnprintf_r, was written so no value arguments need to be queued.
 214
 215 Because strerror is not async signal safe a new function snprinterr was written that replaces the (glibc compatible) %m format with strerror output. The original errno is passed in the message queue, snprinterr is called when dequeuing messages outside of signal handler.
 216
 217 // List of signal handlers in socat
 218 socat.c:socat_signal (generic, just logs and maybe exits)
 219 xioshutdown.c:signal_kill_pid (SIGALRM, kill child process)
 220 xiosigchld.c:childdied (SIGCHLD: get info, log; possibly close channel)
 221 xiosignal.c:socatsignalpass: cascades signal to channel child processes; w/ options sighup,sigint,sigquit
 222 xio-socket.c:xiosigaction_hasread: SIGUSR1,SIGCHLD, tells parent that datagram has been consumed