DEMO_INETD

   1
   2                 Demonstration of Inetd Server Emulation
   3
   4 This demonstration script emulates the standard inetd super-daemon found
   5 on all Unix systems. It showcases the Stem modules Stem::Proc (which
   6 handle processes) and Stem::SockMsg (a socket to message gateway).  This
   7 demonstration runa a single Hub which listens for socket connections on
   8 two ports. When a connection comes in, a new process is spawned which
   9 interacts with the remote client that made the connection. This is
  10 effectively what inetd does but inetd_demo has several major
  11 advantages. StemInetd can insert filters and/or taps in the data stream,
  12 all its connections and status changes can be logged and filtered and it
  13 can be distributed securely across a network.  The demo script is
  14 described in detail below with sections on running, using, configuring
  15 and experimenting with it.
  16
  17 Running inetd_demo
  18
  19 The single Hub inetd demonstration is called inetd_demo and it uses the
  20 inetd.stem configuration file (found in conf/). It is run with the simple
  21 command:
  22
  23 inetd_demo
  24
  25 To exit, just enter 'q' in the inetd_demo script window itself. It will
  26 kill all the other windows and then exit. This will also happen if you
  27 interrupt the demo script with ^C.
  28
  29 If the -s option is used, then all the windows will use ssfe (split
  30 screen front end) which provides a command line edit and history window
  31 section and an output section. A single Hub window named Stem will be
  32 created and then 4 smaller telnet windows which will be connected to
  33 listen sockets in the Stem Hub. These telnet windows are the inetd users
  34 and they can type data and interact with a simple command line server
  35 program named proc_serv. The telnet windows are named A, B, C and D and
  36 if you use ssfe, each will display the telnet command it ran.
  37
  38 Using inetd_demo
  39
  40 Now enter the help command into window A and hit return. These are the
  41 commands you give the proc_serv application. Each of the user windows is
  42 connected to a different running proc_serv process. You can verify this
  43 by running the pid command in each window. Then have fun with the yow
  44 and insult commands. Later in the experimenting section, you can change
  45 the program to run and its options. The major difference among the user
  46 windows is that two of them A and C are connected to the 6666 port in
  47 the Hub and run the proc_serv in normal mode. The B and D windows are
  48 connected to the 6667 port in the Hub and run the proc_serv with -n so
  49 numbers the successful output lines.
  50
  51 You can print out the list of all the registered Cells by sending a
  52 status command message to the Stem:Route Class Cell which is aliased to
  53 'reg'.  In the Hub window (named Stem) type this command:
  54
  55 reg status
  56
  57 You will see this printout:
  58
  59 Route Status for Hub ''
  60
  61         Object Cells with Target names of their Cloned Cells
  62
  63         A                               => Stem::SockMsg=HASH(0x2dd5a0)
  64                 :aaaaaa                 => Stem::SockMsg=HASH(0x2fda20)
  65                 :aaaaab                 => Stem::SockMsg=HASH(0x350ab0)
  66         B                               => Stem::SockMsg=HASH(0x2ed474)
  67                 :aaaaaa                 => Stem::SockMsg=HASH(0x2c10ac)
  68                 :aaaaab                 => Stem::SockMsg=HASH(0x355040)
  69         proc_serv                       => Stem::Proc=HASH(0x2fdbc4)
  70                 :aaaaac                 => Stem::Proc=HASH(0x3515c4)
  71                 :aaaaad                 => Stem::Proc=HASH(0x35554c)
  72                 :aaaaaa                 => Stem::Proc=HASH(0x2f881c)
  73                 :aaaaab                 => Stem::Proc=HASH(0x352660)
  74
  75         Class Cells with their Aliases
  76
  77         Stem::Conf              => conf
  78         Stem::Demo::Cmd         => cmd
  79         Stem::Hub               => hub
  80         Stem::Log               =>
  81         Stem::Log::Entry        => entry
  82         Stem::Portal            => port
  83         Stem::Route             => foo reg
  84         Stem::TtyMsg            => tty
  85         Stem::Vars              => var
  86
  87 This shows the Parent Object Cells A, B and proc_serv each with their
  88 own set of Cloned Cells. Below that are the loaded Class Cells.
  89 The two Stem::SockMsg Cells have 2 telnet users connected to them and
  90 the proc_serv Cell has cloned four Objects, each of which manages a
  91 single process. Note that parent Cells don't do the work, they manage
  92 the Cloned Cells which do it.
  93
  94
  95 How inetd_demo is Configured
  96
  97 Look at the file conf/inetd.stem. That is the configuration file used by
  98 inetd_demo. It is very simple and easy to understand. It is a Perl list
  99 of lists structure with pairs of keys and values. Read the config_notes
 100 for more on this.
 101
 102 The first Cell configured is Stem::TtyMsg which supports typing in and
 103 sending command messages. This is done in all the demo configurations.
 104
 105         [
 106                 class   =>      'Stem::TtyMsg',
 107                 args    =>      [],
 108         ],
 109
 110 Then come two Stem::SockMsg Cells named A and B. Each has a server
 111 socket listening on its own port. Also they each will create a piped
 112 connection to the cell named 'proc_serv'. The Cell B has one extra
 113 attribute set, it adds the -n option when a process is spawned for it.
 114
 115 [
 116         class   =>      'Stem::SockMsg',
 117         name    =>      'A',
 118         args    =>      [
 119                 port            => 6666,
 120                 server          => 1,
 121                 piped_to        => 'proc_serv',
 122         ],
 123 ],
 124 [
 125         class   =>      'Stem::SockMsg',
 126         name    =>      'B',
 127         args    =>      [
 128                 port            => 6667,
 129                 server          => 1,
 130                 piped_to        => 'proc_serv',
 131                 piped_args      => [ '-n' ],
 132         ],
 133 ],
 134
 135
 136
 137 Finally we have the Stem::Proc Cell named 'proc_serv' which can clone
 138 itself and spawn off processes.
 139
 140 [
 141         class   =>      'Stem::Proc',
 142         name    =>      'proc_serv',
 143         args    =>      [
 144                 path            => 'proc_serv',
 145                 use_stderr      => 1,
 146                 piped_to        => 1,
 147                 no_init_spawn   => 1,
 148         ],
 149 ],
 150
 151 The 'path' attribute is the absolute path or program name to
 152 be run. Note that this configuration assumes it will find 'proc_serv in
 153 $PATH. The three boolean attributed tell the Cell that it should handle
 154 output from stderr of the process, it is expecting a pipe connection
 155 request and it should only spawn processes when it has been cloned.
 156
 157
 158 Experimenting with inetd_demo
 159
 160 These experiments are similar to the Hub and Portal ones in
 161 DEMO_CHAT. They show you how to change the processes StemInetd runs, and
 162 to distribute it over multiple systems over secure connections. Choose a
 163 second system and make sure Stem is properly installed on it (NFS
 164 mounting the tarball dir will help).
 165
 166 To support a remote Hub connecting the Hub which owns the Stem::Proc
 167 Cell, you have to add a Stem::Portal Cell to each of them.
 168
 169 Make two copies of the configuration file conf/inetd.stem and call them
 170 inetd_server.stem and inetd_client.stem
 171
 172 Edit inetd_server.stem and rename the Stem::Hub configuration to
 173 inetd_server. Also insert this Stem::Portal Cell configuration into it
 174 replacing 'foo_host' with the server hostname:
 175
 176 [
 177         class   =>      'Stem::Portal',
 178         args    =>      [
 179                 'server'        => 1,
 180                 'host'          => 'foo_host'
 181         ],
 182 ],
 183
 184
 185 Edit inetd_client.stem and rename the Stem::Hub configuration to
 186 inetd_client. Delete the Stem::Proc Cell configuration.  Also insert
 187 this Stem::Portal Cell configuration into it replacing 'foo_host' with
 188 the server hostname:
 189
 190 [
 191         class   =>      'Stem::Portal',
 192         args    =>      [
 193                 'host'          => 'foo_host'
 194         ],
 195 ],
 196
 197
 198 You can create and modify as many of the Stem::SockMsg Cells as you want
 199 on each Hub.  Then in a window on the server box, do:
 200
 201 run_stem inetd_server
 202
 203 and on a window in the other box (called bar_host) where Stem is setup do:
 204
 205 run_stem inetd_client
 206
 207 You can create telnet sessions from the 'server' system that connect
 208 to the ports of the Stem::SockMsg Cells.
 209
 210 telnet localhost 6666
 211 telnet localhost 6667
 212
 213 And on the 'inetd_client' system, connect telnets to the ports of its
 214 Stem::SockMsg Cells.
 215
 216 telnet localhost 6666
 217 telnet localhost 6667
 218
 219 You can now interact with this Stem application just as you did when it
 220 was running on one system as it did with inetd_demo.
 221
 222 Instead of editing the configuration files, you could also set the
 223 Stem::Portal host attribute by setting a command line argument or
 224 environment variable. This command will make the 'server' Hub accept
 225 connections from the 'foo' host interface:
 226
 227 run_stem host=foo chat_server
 228
 229 You can do the same for the 'client' Hub and have it connect to host
 230 'foo'. By setting the STEM_HOST environment variable to the host name
 231 you can get the same effect.