src/NetworkOLK/Tools/README

   1 Welcome to FlightGear Deamon fgd
   2 --------------------------------
   3 Here the first Tools to play with FlightGear Deamon.
   4 This is yet alpha moving to beta and the sources remain to be tidied up,
   5 and to get documented.
   6
   7
   8 Why this software?
   9 ------------------
  10 The goal of the author is to keep unnecessairy jobs out of FGFS. This keeps
  11 FGFS doing what it should do: simulate!
  12 Adding more fancy stuff into FGFS would maybe spoil it's framerates and lead
  13 to larger compiletimes. For that reason an external solution comes in quite
  14 handy. Firing up the deamon on another machine than FGFS is running does not
  15 affect the cpu-time of FGFS. Let the deamon do all the other jobs for your
  16 FGFS, also let *him* communicate with the outer world and present the
  17 results in a "precooked" way.
  18
  19
  20 Theory of operation:
  21 --------------------
  22 The FlightGear Deamon, called fgd, is a standalone program which registers
  23 FGFS players willing to have a multiplayer FGFS environment via TCP/IP.
  24 Information like player's IP/lon/lat/alt etc and also messages can be send
  25 to fgd.
  26
  27 The deamon fgd in turn sends back the gathered information upon request.
  28
  29 The purpose of the scan prog "fgd_scan" is to locate free ports on the
  30 network, which can be used for exchanging data between FGFS and fgd.
  31
  32 The commando program "fgd_com" serves as an example of how the communication
  33 to fgd can be done. For the moment, the functionality of fgd_com is not yet
  34 integrated into FGFS. Parts of fgd_com will be later incorporated into FGFS.
  35
  36 The master control program "fgd_mcp" is some sort virtual fgfs. It simulates
  37 up to x FlightGear simulators. It's main purpose is being a development
  38 platform for network related stuff. The coolest advantage here is the
  39 possibilty of having multiple fgfs's in one little program. That saves *much*
  40 memory and also time because recompiling fgd_mcp is way faster then FGFS.
  41
  42
  43 How to play with the tools:
  44 ---------------------------
  45 Just fire up fgd on whatever machine reachable from the one on which FGFS
  46 will be running. Even the same machine is ok.
  47 Then use fgd_scan to locate the fgd-deamon.
  48 Also use fgd_com to pass some commandos to fgd.
  49 Try setting up various scenarios with fgd_mcp and see if everything works.
  50
  51
  52 How to compile:
  53 ---------------
  54 Have a look at the HEADERS file and check the presence of the required headers
  55 on your machine and adjust them in the fgd.h file just in case of being located
  56 elsewhere. This software is libc5 proof, so maybe on glibc (>=2), the header
  57 files will be located elsewhere.
  58
  59 Use the Makefile with make or just gcc -o prog prog.c
  60 Default location for "make" is current directory, so be sure to have r/w-access
  61 to it. For "make install" you have to be root, binaries go by default into
  62 /usr/local/bin.
  63
  64
  65 Usage:
  66 ------
  67 - fgd [start port] [end port] [name] <-v -vv>
  68
  69 where
  70       - start port  and  end port is the (numeric) range where it should
  71         listen and talk to. (Later the range will be used to check for a
  72         free port within this range, which can be used for communicating
  73         with FGFS.
  74         for the moment make sure you use the _SAME_ port value for start
  75         and stop. A good starting point should be above or equal 10000.
  76       - name (string) of the deamon.
  77       - -v or -vv is the verbose level. This param can be ommitted.
  78
  79         Be careful, trying fgd on a used port doesn't work. Also it doesn't
  80         make any sense and luckyly doesn't goof the service of the used port.
  81         Just in case you did fgd will complain and advise you to look for an
  82         unused port first.
  83
  84
  85 - fgd_scan [host] [start port] [end port] <-v -vv>
  86
  87 comment: params are the same as for fgd except that the start/stop values
  88          should be different to detect fgd. In case of knowning the port,
  89          which fgd uses, one should of course set equal port-values.
  90
  91          Also host means the host running fgd, not where the scanner is
  92          fired up.
  93
  94          Just for fun you can take also the dangerous (priviledged ports)
  95          But the fgd-scanner could maybe get stuck at some used ports.
  96          It doesn't hurt to experiment in the used regions, a ctrl-c
  97          will abort the scanning so that new params can be used.
  98
  99
 100 ACHTUNG!      A well configured system, in this case the target-ip the
 101               scanner inquires, will log the replies of various services
 102               trying to react to the scanner. It depends on the vigilance
 103               and mood of the respective sysadmin what will happen to the
 104               *evil* person sending requests to the target system.
 105               Scanning unused ports doesn't hurt at all.
 106
 107               Have a look at the "/etc/services" file which describes all
 108               the "official" services & deamons lurking on various ports.
 109
 110
 111 - fgd_com  [FGD-host] [start port] [end port] [-v -vv] [commando] <FGFS-host>
 112
 113 comment: like fgd_scan, but you must enter either an ip (numeric) or alias
 114          (string) or a fqdn (like foo.bar.com) or dummystring as last parameter
 115          here: <FGFS-host>.
 116          Some commandos use it to pass it as real information to fgd. Maybe the
 117          start/end port options will go away later because it's the job of the
 118          scanner to find fgd within a range.
 119          It's a waste to spoil the net with commands (tcp-packets).
 120
 121
 122 - fgd_mcp
 123
 124 comment: works like fgd_com except that it is *not* a single shot program as
 125          the other programs, yes it works interactively so you have to enter
 126          all relevant values yourself at runtime. You can stresstest any
 127          FlightGear deamon to see if it responds a) accurate b) fast enough.
 128
 129          You can enter a Flight route just by entering the start/stop coords
 130          and the speed. This master control program will then automagically
 131          send information about current aircraft to the deamon, like a real
 132          FGFS would do.
 133
 134          You can even define multiple scenarios. That means that all defined
 135          aircrafts fly simultaneous at the same time.
 136          Relevant params here are alt, lon, lat, speed, roll, pitch, yaw,
 137          pilot, model, start/stop-coords and update frequency.
 138
 139          Watch out for broken pipes, never had any in a xterm but often on
 140          text consoles. They will go away when the "recv"-loops will be
 141          replaced by "select"-calls.
 142
 143          The default values suit my personal needs. So don't be paniked if
 144          you get some errormessages. You just have to adjust some values
 145          like IP's and HOST-names in either sourcecode or to enter them at
 146          runtime.
 147
 148
 149 The commandos for fgd_com:
 150 --------------------------
 151
 152  0 : fgd identifies itself and answeres back to scanner
 153  1 : registering to fgd
 154  2 : show who's registered
 155  3 : send message to one specific user           (not implemented yet)
 156  4 : send message to all users                   (not implemented yet)
 157  5 : scan for other fgd's                        (not implemented yet)
 158  6 : push (fgd_com sends FGFS-data to fgd)       (not implemented yet)
 159  7 : pop  (fgd_com receives data from fgd)       (not implemented yet)
 160  8 : unregister from fgd
 161  9 : shutdown fgd
 162
 163 Comments:
 164 ---------
 165 Commandos 1/2/8 use the last parameter (see above, dummy-string) for the
 166 ip or hostname or fqdn of the fgfs-machine which will be added/listed/removed
 167 from fgd.
 168
 169 Commandos 3+4 are some sort of "talk" to registered users on fgd.
 170 The messages are keyed in, then send and stored into fgd until the
 171 recepient user requests fgd data via command 7 (pop).
 172
 173 Command 5 scans the net (within a range given) for other fgd-deamons.
 174
 175 Commandos 6+7 are seperated send/receive requests to/from fgd.
 176 Later it will be FGFS who queries fgd in given intervalls. By now it's
 177 the user who sends/receives at will via menu or keyboard while flying.
 178
 179 Command 9 is a remote shutdown for fgd. This at least avoids telnetting
 180 to the remote machine, where fgd is fired up. Caveat Emptor: be careful,
 181 everybody connected to fgd can send the "fgd-shutdown"-command. And hey,
 182 also everybody can unregister another user...
 183
 184 Since all FGFS pilots are friendly and Multipilot-mode is considered
 185 cooperative rather then deathmatch, I don't expect any malicious mis-use
 186 of Multipilot-mode, err...yes?  Also this keeps me from adding foolproof
 187 if/then/else-stuff because FGFS is a serious Simulation Software used by
 188 serious people who *know* what they are doing, even if they store FGFS in
 189 directories like:
 190   /usr/games/fgfs   or   D:\SPEL\FlightGear  or  /home/olk/spiele/fgfs
 191
 192 Try registering and unregistering various hosts to see if the add/remove
 193 mechanism works well. It should work correctly as it can be veryfied
 194 with the "2" command.
 195
 196
 197 Examples:
 198 ---------
 199 - fgd 10003 10003 Johnney -vv
 200   fgd runs locally on port "10003" called "Johnney" using max. verbose level
 201
 202 - fgd_scan olk 1 1024 -vv
 203   scans for flightgear deamons on host "olk" using ports "1" thru "1024"
 204   beeing very verbose. Using ports below 10000 is, err...you know.
 205
 206 - fgd_com olk 10003 10003 -vv 1 johnny
 207   send "register host"-command to fgd running on host "olk" using port"10003"
 208   and register machine "johnny", here "johnny" is a fqdn.
 209
 210 - fgd_mcp  (without any commandline params)
 211
 212
 213 To do:
 214 ------
 215 - modify FGFS to talk to fgd and display the data on HUD and draw any found
 216   pilot's aircraft within visible area
 217 - porting to Mac and Windows(95/98/2K/NT)
 218 - clean-up code
 219 - replace "recv"-loops by "select" (blocking vs nonblocking discussion)
 220 - concatenate the elements of one command into one single net-call instead
 221   of sending each element seperately !!!
 222 - reducing of data to be transfered - here: wiping out redundancy,
 223   computers can be upgraded easily but upgrading the bandwith of the net is
 224   almost impossible ;-((
 225 - document the code
 226 - convert code from c to c++ ?
 227 - find a place within FGFS, where to reside
 228 - make fgd a *REAL* deamon which is forked in background
 229 - make fgd concurrent instead of iterative, hmmm...
 230 - make the code more autodetectable, to reduce commandline params
 231 - implement missing commands
 232 - find other useful commands
 233 - find and resolve bugs ;-)
 234
 235
 236 History:
 237 --------
 238   v0.1pre-alpha: May 25 1999 -> First release
 239   v0.1-alpha   : Nov 08 1999 -> Introducing fgd-Master-Control-Program
 240                                 Some cleanups, implementing missing commands
 241                                 of fgd_com into fgd_mcp
 242                  Nov 29 1999 -> Implementing scenario functions like virtual
 243                                 Pilots
 244                  Nov 30 1999 -> ???
 245   v0.1-beta    : Jan 16 2000 -> Several libc5, glibc-2.0 and glibc-2.1
 246                                 issues cleaned up
 247
 248
 249 Future Plans:
 250 -------------
 251   Adding support for downloading files from Webserververs or FTP sites,
 252   eg. weather data (METAR) and passing the infos to FGFS.
 253
 254   Adding some sort of "Tower Control" to the deamon. It could for instance
 255   calculate the nearest airport for each pilot.
 256
 257   Modifying FGFS in a way to accept foreign-data. A so called remote-used
 258   FGFS could display another view of the same flight. Well this requires
 259   at least two or more machines, err...hummm.
 260   On the other hand a remote used FGFS could serve as a teaching facility,
 261   watching somebody else's fly could be very instructive ;-)
 262
 263   Another idea is to implement "black box" features into fgd. The deamon
 264   would serve here as a flightrecorder. By this one could review a past
 265   flight or any flight recorded by somebody else. The recorded "scenario files"
 266   could be read by any deamon and serve as input data for any FGFS switched
 267   into remote mode, see above paragraph.
 268
 269
 270 Thanks:
 271 -------
 272   - W.Richard Stevens+, for his fantastic Unix Network Programming books
 273   - Tennessee Carmel-Veilleux, e-mail: veilleux@ameth.org, for his portscan
 274     program which inspired me writing the FlightGear metwork support.
 275
 276
 277 REMEMBER:
 278 ---------
 279 Those 4 toys are alpha and dirty and need also to be documented.
 280 The programs are fairly well tested under Linux only, but the code should
 281 conform to Unix98.
 282
 283 This software is OPEN SOURCE SOFTWARE, this helps to avoid this package to
 284 be involved into _EVIL_ discussions about copyrights etc...
 285 You can do whatever you want with this software, even enhance it.
 286
 287 Send comments/flames/BEER/whatever to delise@mail.isis.de
 288
 289 Oliver Delise Jan/16/00