%
% socat.tex
% Last Update: $Id$
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Kapitel Socat %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das Socat-Paket}


\section{Die Einleitung}

    Socat (Multipurpose Relay - SOcket CAT) ist ein Kommandozeilenprogramm
    welches zwei bidirektionale Byte-Streams etabliert und Daten dar"uber
    austauscht. Da die Streams aus einer gro"sen Anzahl verschiedener Quell-
    und Zieltypen konstruiert, und eine Vielzahl von Adressoptionen auf die
    Streams angewendet werden k"onnen, kann socat zu unterschiedlichsten
    Zwecken genutzt werden.

\section{Die Funktionen}

    Das Socat-Paket besteht aus folgenden Komponenten:

    \begin{itemize}
        \item Multipurpose Relay - SOcket CAT - Programmdateien.\\
            (\url{http://www.dest-unreach.org/socat/})
    \end{itemize}

\section{Die Voraussetzungen}

    Dieses Paket ben"otigt keine weiteren Pakete um funktionieren zu k"onnen.


\section{Die Installation}

    Das Socat-Paket wird "uber das Setup-Men"u installiert. Wird eine "altere
    Paketversion vorgefunden, so wird diese deinstalliert bevor die neuen
    Programmdateien installiert werden.


\section{Das Men"u im Setup-Programm}

    Das Men"u im Setup-Programm ist wie folgt aufgebaut:

    \begin{itemize}
        \item View documentation: Anzeigen der Dokumentation
        \item Edit configuration: Bearbeiten der Konfiguration
        \item Advanced configuration file handling: Konfigurationen verwalten
        \item Show status: Status der socat-Befehle anzeigen
        \item Stop service: socat-Befehle stoppen
        \item Start service: socat-Befehle starten
        \item Return: Untermen"u verlassen
    \end{itemize}

    Die Men"upunkte d"urften selbsterkl"arend sein, da sie keinerlei weitere
    Eingaben erwarten. Aus diesem Grund wird auf deren Funktion nicht weiter
    eingegangen.


\section{Die "Anderung der Konfiguration}

    Die Konfiguration kann "uber den Men"upunkt 'Edit configuration'
    ge"andert werden. Standardm"a"sig wird der Editor aufgerufen, der in der
    Environment-Konfiguration "uber die Variable 'EDITOR' festgelegt wurde.
    Nachdem der Editor beendet wurde wird abgefragt, ob die Konfiguration
    aktiviert werden soll. Wird dies best"atigt, werden "uber ein Skript die
    Anpassungen umgehend wirksam gemacht.


\section{Die Konfigurationsdatei}

    In der Konfigurationsdatei, die "uber das Men"u zug"anglich ist, sind
    folgende Parameter vorhanden; wer sie von Hand editieren will findet
    sie unter /etc/config.d/socat.


\section{Die Parameter}

\begin{description}
%%  JED - show this description only in the help file
 %  \config{SOCAT\_DO\_DEBUG}{SOCAT\_DO\_DEBUG}{SOCATDODEBUG}
 %      Optionaler Parameter: Um den Debug-Modus zu aktivieren muss dieser
 %      Parameter auf den Wert `yes' gesetzt werden. Um den Debug-Modus zu
 %      deaktivieren  muss der Wert auf `no' gesetzt werde.
 %
 %      G"ultige Werte: yes, no
 %
 %      Standardeinstellung: \texttt{SOCAT\_DO\_DEBUG='no'}

    \config{START\_SOCAT}{START\_SOCAT}{STARTSOCAT}
        Um das Socat-Paket zu aktivieren muss dieser Parameter auf den Wert
        `yes' gesetzt werden. Um das Socat-Paket zu deaktivieren muss der Wert
        auf `no' gesetzt werde.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{START\_SOCAT='no'}

    \config{SOCAT\_EXEC\_N}{SOCAT\_EXEC\_N}{SOCATEXECN}
        "Uber diesen Parameter wird die Anzahl der auszuf"uhrenden socat-Befehle
        angegeben.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{SOCAT\_EXEC\_N='0'}

    \config{SOCAT\_EXEC\_x\_ACTIVE}{SOCAT\_EXEC\_x\_ACTIVE}{SOCATEXECxACTIVE}
        Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der Datensatz
        aktiviert, der Wert `no' deaktiviert ihn.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{SOCAT\_EXEC\_1\_ACTIVE='no'}

    \config{SOCAT\_EXEC\_x\_COMMENT}{SOCAT\_EXEC\_x\_COMMENT}{SOCATEXECxCOMMENT}
        Dies ist ein Kommentarfeld, welches einzig der Beschreibung des
        auszuf"uhrenden socat-Befehls dient.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{SOCAT\_EXEC\_1\_COMMENT='My first socat command'}

    \config{SOCAT\_EXEC\_x\_OPTIONS}{SOCAT\_EXEC\_x\_OPTIONS}{SOCATEXECxOPTIONS}
        "Uber diesen Parameter werden die socat-Optionen angegeben, die beim
        Befehlsaufruf "ubergeben werden sollen. Eine Syntaxpr"ufung etc. findet
        nicht statt, sodass man dies vorab selbst pr"ufen muss.

        G"ultige Werte: g"ultige socat-Befehlsoptionen

        Beispiel: \texttt{SOCAT\_EXEC\_1\_OPTIONS='pty,link=/dev/netcom0,group=nogroup,mode=0660 tcp:192.168.6.254:100'}
\end{description}

\section{Verschiedenes}

\begin{description}
    \config{socat-Befehlsoptionen}{socat-Befehlsoptionen}{socat-Befehlsoptionen}
        Folgende Befehlsoptionen stehen in der socat-Version 2.0.0-b7 zur
        Verf"ugung:

        \begin{verbatim}
socat by Gerhard Rieger - see www.dest-unreach.org

Usage:
  socat [options] <bi-address> <bi-address>

options:
  -V     print version and feature information to stdout, and exit
  -h|-?  print a help text describing command line options and
         addresses
  -hh    like -h, plus a list of all common address option names
  -hhh   like -hh, plus a list of all available address option
         names
  -d     increase verbosity (use up to 4 times; 2 are recommended)
  -D     analyze file descriptors before loop
  -ly[facility]  log to syslog, using facility (default is daemon)
  -lf<logfile>   log to file
  -ls            log to stderr (default if no other log)
  -lm[facility]  mixed log mode (stderr during initialization,
                 then syslog)
  -lp<progname>  set the program name used for logging
  -lu            use microseconds for logging timestamps
  -lh            add hostname to log messages
  -v     verbose data traffic, text
  -x     verbose data traffic, hexadecimal
  -b<size_t>     set data buffer size (8192)
  -s     sloppy (continue on error)
  -t<timeout>    wait seconds before closing second channel
  -T<timeout>    total inactivity timeout in seconds
  -u     unidirectional mode (left to right)
  -U     unidirectional mode (right to left)
  -g     do not check option groups
  -L <lockfile>  try to obtain lock, or fail
  -W <lockfile>  try to obtain lock, or wait
  -4     prefer IPv4 if version is not explicitly specified
  -6     prefer IPv6 if version is not explicitly specified

bi-address:
  pipe[,<opts>]	groups=FD,FIFO
  <single-address>%<single-address>
  <single-address>

single-address:
  <address-head>[,<opts>]

address-head:
  abstract-client:<filename>          rwb     groups=FD,SOCKET,
                                              RETRY,UNIX
  abstract-connect:<filename>         rwb     groups=FD,SOCKET,
                                              RETRY,UNIX
  abstract-listen:<filename>          rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              UNIX
  abstract-recv:<filename>            r       groups=FD,SOCKET,
                                              RETRY,UNIX
  abstract-recvfrom:<filename>        r b     groups=FD,SOCKET,
                                              CHILD,RETRY,UNIX
  abstract-sendto:<filename>           wb     groups=FD,SOCKET,
                                              RETRY,UNIX
  create:<filename>                   rwb     groups=FD,REG,NAMED
  exec:<command-line>                 rwb     groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  exec:<command-line>                 r    w  groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  exec:<command-line>                  w  r   groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  exec:<command-line>                   b   b groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  exec1:<command-line>                 w  r   groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  fd:<num>                            rwb     groups=FD,FIFO,BLK,
                                              REG,SOCKET,TERMIOS,
                                              UNIX,IP4,IP6,UDP,
                                              TCP,SCTP
  fd:<numout>:<numin>                   b     groups=FD,FIFO,BLK,
                                              REG,SOCKET,TERMIOS,
                                              UNIX,IP4,IP6,UDP,
                                              TCP,SCTP
  gopen:<filename>                    rwb     groups=FD,FIFO,BLK,
                                              REG,SOCKET,NAMED,
                                              OPEN,TERMIOS,UNIX
  interface:<interface>               rwb     groups=FD,SOCKET
  ip-datagram:<host>:<protocol>       rwb     groups=FD,SOCKET,
                                              RANGE,IP4,IP6
  ip-recv:<protocol>                  r       groups=FD,SOCKET,
                                              RANGE,IP4,IP6
  ip-recvfrom:<protocol>              r b     groups=FD,SOCKET,
                                              CHILD,RANGE,IP4,IP6
  ip-sendto:<host>:<protocol>          wb     groups=FD,SOCKET,
                                              IP4,IP6
  ip4-datagram:<host>:<protocol>      rwb     groups=FD,SOCKET,
                                              RANGE,IP4
  ip4-recv:<protocol>                 r       groups=FD,SOCKET,
                                              RANGE,IP4
  ip4-recvfrom:<protocol>             r b     groups=FD,SOCKET,
                                              CHILD,RANGE,IP4
  ip4-sendto:<host>:<protocol>         wb     groups=FD,SOCKET,
                                              IP4
  ip6-datagram:<host>:<protocol>      rwb     groups=FD,SOCKET,
                                              RANGE,IP6
  ip6-recv:<protocol>                 r       groups=FD,SOCKET,
                                              RANGE,IP6
  ip6-recvfrom:<protocol>             r b     groups=FD,SOCKET,
                                              CHILD,RANGE,IP6
  ip6-sendto:<host>:<protocol>         wb     groups=FD,SOCKET,
                                              IP6
  nop                                 r    w  groups=
  nop                                  w  r   groups=
  nop                                   b   b groups=
  open:<filename>                     rwb     groups=FD,FIFO,BLK,
                                              REG,NAMED,OPEN,
                                              TERMIOS
  openssl-client                      rwb   b groups=CHILD,RETRY,
                                              OPENSSL
  openssl-client:<host>:<port>        rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,IP6,
                                              TCP,OPENSSL
  openssl-server                      rwb   b groups=CHILD,RETRY,
                                              OPENSSL
  openssl-server:<port>               rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP4,IP6,TCP,
                                              OPENSSL
  pipe                                  b     groups=FD,FIFO,
                                              NAMED,OPEN
  pipe:<filename>                     rwb     groups=FD,FIFO,
                                              NAMED,OPEN
  proxy:<host>:<port>                 rwb   b groups=CHILD,RETRY,
                                              HTTP
  proxy:<proxy-server>:<host>:<port>  rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,IP6,
                                              TCP,HTTP
  pty                                 rwb     groups=FD,NAMED,
                                              TERMIOS,PTY
  pty:<symlink>                       rwb     groups=FD,NAMED,
                                              TERMIOS,PTY
  sctp-connect:<host>:<port>          rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,IP6,
                                              SCTP
  sctp-listen:<port>                  rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP4,IP6,SCTP
  sctp4-connect:<host>:<port>         rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,SCTP
  sctp4-listen:<port>                 rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP4,SCTP
  sctp6-connect:<host>:<port>         rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP6,SCTP
  sctp6-listen:<port>                 rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP6,SCTP
  socket-connect:<domain>:<protocol>:<remote-address>  rwb
                                              groups=FD,SOCKET,
                                              CHILD,RETRY
  socket-datagram:<domain>:<type>:<protocol>:<remote-address>  rwb
                                              groups=FD,SOCKET,
                                              RANGE
  socket-listen:<domain>:<protocol>:<local-address>  rwb
                                              groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE
  socket-recv:<domain>:<type>:<protocol>:<local-address>  r
                                              groups=FD,SOCKET,
                                              RANGE
  socket-recvfrom:<domain>:<type>:<protocol>:<local-address>  rwb
                                              groups=FD,SOCKET,
                                              CHILD,RANGE
  socket-sendto:<domain>:<type>:<protocol>:<remote-address>  rwb
                                              groups=FD,SOCKET
  socks4:<host>:<port>                rwb   b groups=CHILD,RETRY,
                                              SOCKS4
  socks4:<socks-server>:<host>:<port> rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,IP6,
                                              TCP,SOCKS4
  socks4a:<host>:<port>               rwb   b groups=CHILD,RETRY,
                                              SOCKS4
  socks4a:<socks-server>:<host>:<port>rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,IP6,
                                              TCP,SOCKS4
  socks5:<host>:<port>                rwb   b groups=SOCKS5
  stderr                               w      groups=FD,FIFO,BLK,
                                              REG,SOCKET,TERMIOS,
                                              UNIX,IP4,IP6,UDP,
                                              TCP,SCTP
  stdin                               r       groups=FD,FIFO,BLK,
                                              REG,SOCKET,TERMIOS,
                                              UNIX,IP4,IP6,UDP,
                                              TCP,SCTP
  stdio                               rwb     groups=FD,FIFO,BLK,
                                              REG,SOCKET,TERMIOS,
                                              UNIX,IP4,IP6,UDP,
                                              TCP,SCTP
  stdout                               w      groups=FD,FIFO,BLK,
                                              REG,SOCKET,TERMIOS,
                                              UNIX,IP4,IP6,UDP,
                                              TCP,SCTP
  system:<shell-command>              rwb     groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  system:<shell-command>                b   b groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  system:<shell-command>              r    w  groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  system:<shell-command>               w  r   groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  system1:<shell-command>              w  r   groups=FD,FIFO,
                                              SOCKET,EXEC,FORK,
                                              TERMIOS,PTY,PARENT,
                                              UNIX
  tcp-connect:<host>:<port>           rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,IP6,
                                              TCP
  tcp-listen:<port>                   rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP4,IP6,TCP
  tcp4-connect:<host>:<port>          rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP4,TCP
  tcp4-listen:<port>                  rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP4,TCP
  tcp6-connect:<host>:<port>          rwb     groups=FD,SOCKET,
                                              CHILD,RETRY,IP6,TCP
  tcp6-listen:<port>                  rwb     groups=FD,SOCKET,
                                              LISTEN,CHILD,RETRY,
                                              RANGE,IP6,TCP
  test                                r    w  groups=
  test                                 w  r   groups=
  test                                  b   b groups=
  testrev                              w  r   groups=
  testuni                              w  r   groups=
  tun:<ip-addr>/<bits>                rwb     groups=FD,NAMED,
                                              OPEN,INTERFACE
  udp-connect:<host>:<port>           rwb     groups=FD,SOCKET,
                                              IP4,IP6,UDP
  udp-datagram:<host>:<port>          rwb     groups=FD,SOCKET,
                                              RANGE,IP4,IP6,UDP
  udp-listen:<port>                   rw      groups=FD,SOCKET,
                                              LISTEN,CHILD,RANGE,
                                              IP4,IP6,UDP
  udp-recv:<port>                     r       groups=FD,SOCKET,
                                              RANGE,IP4,IP6,UDP
  udp-recvfrom:<port>                 r b     groups=FD,SOCKET,
                                              CHILD,RANGE,IP4,IP6,
                                              UDP
  udp-sendto:<host>:<port>             wb     groups=FD,SOCKET,
                                              IP4,IP6,UDP
  udp4-connect:<host>:<port>          rwb     groups=FD,SOCKET,
                                              IP4,UDP
  udp4-datagram:<host>:<port>         rwb     groups=FD,SOCKET,
                                              IP4,UDP
  udp4-listen:<port>                  r b     groups=FD,SOCKET,
                                              LISTEN,CHILD,RANGE,
                                              IP4,UDP
  udp4-recv:<port>                    r       groups=FD,SOCKET,
                                              RANGE,IP4,UDP
  udp4-recvfrom:<host>:<port>         r b     groups=FD,SOCKET,
                                              CHILD,RANGE,IP4,UDP
  udp4-sendto:<host>:<port>            wb     groups=FD,SOCKET,
                                              IP4,UDP
  udp6-connect:<host>:<port>          rwb     groups=FD,SOCKET,
                                              IP6,UDP
  udp6-datagram:<host>:<port>         rwb     groups=FD,SOCKET,
                                              IP6,UDP
  udp6-listen:<port>                  r b     groups=FD,SOCKET,
                                              LISTEN,CHILD,RANGE,
                                              IP6,UDP
  udp6-recv:<port>                    r       groups=FD,SOCKET,
                                              RANGE,IP6,UDP
  udp6-recvfrom:<port>                r b     groups=FD,SOCKET,
                                              CHILD,RANGE,IP6,UDP
  udp6-sendto:<host>:<port>            wb     groups=FD,SOCKET,
                                              IP6,UDP
  unix-client:<filename>              rwb     groups=FD,SOCKET,
                                              NAMED,RETRY,UNIX
  unix-connect:<filename>             rwb     groups=FD,SOCKET,
                                              NAMED,RETRY,UNIX
  unix-listen:<filename>              rwb     groups=FD,SOCKET,
                                              NAMED,LISTEN,CHILD,
                                              RETRY,UNIX
  unix-recv:<filename>                r       groups=FD,SOCKET,
                                              NAMED,RETRY,UNIX
  unix-recvfrom:<filename>            r b     groups=FD,SOCKET,
                                              NAMED,CHILD,RETRY,
                                              UNIX
  unix-sendto:<filename>               wb     groups=FD,SOCKET,
                                              NAMED,RETRY,UNIX
        \end{verbatim}
\end{description}
