[Olsr-dev] New plugin: telnet

[equinox]

Hi,

I wrote a small telnet plugin which allows to change some configuration 
options on the fly (without the need to restart the daemon). See detailed
description below...
I also added a tar.gz containing the patch set which is based on current 
master branch of the official git repo.

Please have a look and tell me if you are willing to accept it. Also it would
be nice if some of you could check if everything the plugin does is ok. I tested 
with valgrind and don't think that there are memory leaks but it would be good if 
somebody who knows the internal data structures would take a look at what i'm doing.
Especially with adding/enabling and removing/disabling interfaces i'm not complete
certain....

Thanks in advance!

regards
 christian

--- 

TELNET PLUGIN for OLSRd
=======================

The telnet plugin runs a small telnet server which enables the user to
update parts of the olsrd configuration at runtime without the need to
restart the whole daemon.
For now adding and removing interfaces as well as adding and removing
HNA entries is supported, but others may follow.
Other plugins can add their own commands (see FOREIGN COMMANDS)


PLUGIN USAGE
============

To use the plugin one just has to enable the plugin (see PLUGIN CONFIGURATION)
and connect to it using telnet, nc or the like. There are two built-in
functions quit and help.
Besides that there are commands for altering and inspecting HNA and
interface lists. A command that allows to alter LQ multipliers and a command
to terminate the whole olsr daemon.
These commands can be globally disabled (see PLUGIN CONFIGURATION). The
built-in commands are always enabled.


PLUGIN CONFIGURATION
====================

LoadPlugin "olsrd_telnet.so.0.1"
{
    # the default port is 2023 but you can change it like this:
    #PlParam      "port"   "1234"

    # the address to bind the socket to, if omitted the plugin
    # will bind to the wildcard adress
    #PlParam      "listen" "127.0.0.1"

    # whitelist for commands, one line per command, if omitted all commands
    # are enabled
    # mind that the built-in functions (quit and help) are always enabled
    # and that depending on 'allowforeign' other plugins may add commands
    #PlParam      "enable" "hna"
    #PlParam      "enable" "interface"
    #PlParam      "enable" "lqmult"
    #PlParam      "enable" "terminate"

    # allow other plugins to add commands to the command table
    # by default this is not allowed
    #PlParam      "allowforeign" "yes"
}


Command Reference
=================

quit
----
 This command terminates the client connection.

 Usage:
   quit

help
----
 This command can be used to print a list of all available commands or the usage
 of a given command.

 Usage:
   help [<command>]

hna
---
 This command can be used to add, remove and list HNA entries.

 Usage:
   hna (add|del) <address>/<netmask>
   hna list

interface
---------
 This command enables/disables, adds/removes or lists interfaces to/from olsrd.
 Newly added interfaces inherit their configuration (includeing LQ multipliers)
 from interface defaults. If an interface gets removed and re-added all special
 settings (LQ multipliers, timings,...) get lost. To preserve the configuration
 `disable` may be used. A disabled interface can be re-enbaled using `enable`.
 The `status` command prints current addresses and some other information for a
 specific interface. `list` prints all interfaces and their current status.

 Usage:
   interface (enable|disable) <name>
   interface (add|del) <name>
   interface status <name>
   interface list

lqmult
------
 This command alters LQ multipliers for an given neighbor on one or all
 interfaces. `add` inserts a new multiplier (error if exists), `update` changes
 an existing multiplier (error if not exists). `set` adds or updates a
 multiplier. Multipliers can be removed using `del` or `flush`. `del` only
 deletes one multiplier whereas `flush` removes all multipliers from a given
 or from all interfaces. `get` can be used to retrieve the current  multiplier
 value(s) of a given neighbor. `list` prints all multipliers by interface.

 Usage:
   lqmult (add|update|set) (<interface>|*) <neigbor> <value>
   lqmult del (<interface>|*) <neigbor>
   lqmult get (<interface>|*) <neigbor>
   lqmult flush [<interface>]
   lqmult list [<interface>]

terminate
---------
 This command terminates olsrd. To prevent accidential invocation this command
 must be aknowledged.

 Usage:
   terminate


Example Usage
=============

The tools directory contains some scripts which use `empty` to add/remove
HNA entries. This is particulary useful if you want to update the HNA list
from shell scripts whithout the need to restart the whole daemon.


FOREIGN COMMANDS
================

If you want to add custom commands (from an other plugin) you have to
write something like this:

<snip>
#include "../../telnet/include/telnet_cmd.h"

DEFINE_TELNET_CMD(cmd_mycmd_struct,
                  "mycmd", handle_mycmd,
                  "short help text",
                  " usage text (line 1)\n\r"
                  " usage text (line 2)");

static telnet_cmd_function handle_mycmd(int c, int argc, char* argv[])
{
  if(argc != 1) {
    telnet_print_usage(c, cmd_mycmd_struct);
    return NULL;
  }

  /* do something useful or cool or at least funny ;) */
  if(success) {
    telnet_client_printf(c, "it worked!\n\r");
    return NULL;
  }

  telnet_print_usage(c, cmd_mycmd_struct);
  return NULL;
}
</snip>

You can enable your command by calling:

<snip>
telnet_cmd_add(&cmd_mycmd_struct);
</snip>

your handle function may use the following functions:
 - telnet_print_usage(c, cmd_t)        print the usage string for the command
 - telnet_client_printf(c, fmt, ...)   print something to the connected client
 - telnet_client_quit(c)               terminate the client connection

To keep the interface header-only all these functions as well as `telnet_cmd_add`
are implemented as macros.
If your command needs additional input from the user, your handle function may
return a pointer to a continue function which will be called next time the user
enters something, bypassing the normal command lookup. This may be done
repeatedly until the command is completed. The `terminate` command is a nice
example for such an inquiry.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: telnet_plugin.tar.gz
Type: application/x-tar
Size: 76438 bytes
Desc: not available
URL: <http://lists.olsr.org/pipermail/olsr-dev/attachments/20130220/e67210bf/attachment.tar>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: OpenPGP digital signature
URL: <http://lists.olsr.org/pipermail/olsr-dev/attachments/20130220/e67210bf/attachment.sig>