NAME

aemp - AnyEvent:MP utility

SYNOPSIS

aemp command args...

# protocol commands
aemp snd <port> <arg...>      # send a message
aemp mon <port>               # wait till port is killed
aemp rpc <port> <arg...>      # send message, append reply
aemp eval <node> <expr...>    # evaluate expression
aemp trace <nodeid>           # trace the network topology

# run a node
aemp run configure_args...    # run a node

# node configuration: node ID
aemp setnodeid <nodeid>       # configure the real node id
aemp delnodeid                # reset node id to default (= inherit)

# node configuration: secret
aemp gensecret                # generate a random shared secret
aemp setsecret <secret>       # set the shared secret
aemp delsecret                # remove the secret (= inherit)

# node configuration: TLS
aemp gencert                  # generate a random certificate
aemp setcert <file>           # set a certificate (key.pem + certificate.pem)
aemp delcert                  # remove certificate (= inherit)

# node configuration: seed addresses for bootstrapping
aemp setseeds <host:port>,... # set seeds
aemp delseeds                 # clear all seeds (= inherit)
aemp addseed <host:port>      # add a seed
aemp delseed <host:port>      # remove seed

# node configuration: bind addresses
aemp setbinds <host:port>,... # set binds
aemp delbinds                 # clear all binds (= inherit)
aemp addbind <host:port>      # add a bind address
aemp delbind <host:port>      # remove a bind address

# node configuration: services
aemp setservices initfunc,... # set service functions
aemp delservices              # clear all services (= inherit)
aemp addservice <initfunc>    # add an instance of a service
aemp delservice <initfunc>    # delete one instance of a service

# profile-specific configuration
aemp profile <name> <command>... # apply command to profile only
aemp setparent <name>         # specify a parent profile
aemp delparent                # clear parent again
aemp delprofile <name>        # eradicate the named profile
aemp showprofile <name>       # display given profile
aemp showconfig <name> ...    # display effective config

DESCRIPTION

With aemp you can configure various aspects of AnyEvent::MP and its protocol, send various messages and even run a node.

The aemp utility works like cvs, svn or other commands: the first argument defines which operation (subcommand) is requested, after which arguments for this operation are expected. When a subcommand does not eat all remaining arguments, the remaining arguments will again be interpreted as subcommand and so on.

This means you can chain multiple commands, which is handy for profile configuration, e.g.:

aemp gensecret profile xyzzy binds 4040,4041 nodeid anon/

Please note that all setxxx subcommands have an alias without the set prefix.

RUNNING A NODE

This can be used to run a node - together with some services, this makes it unnecesary to write any wrapper programs.

run <profile> <...>

Runs a node by calling AnyEvent::MP::Kernel::configure with the given arguments. The node runs under AnyEvent::Watchdog, can be restarted (and autorestarted, see the AnyEvent::Watchdog manual).

Care has been taken to load (almost) no modules other than AnyEvent::Watchdog and the modules it loads, so everything (including the AnyEvent::MP modules themselves) will be freshly loaded on restart, which makes upgrading everything except the perl binary easy.

PROTOCOL COMMANDS

These commands actually communicate with other nodes. They all use a node profile name of aemp (specifying a dfeault node ID of anon/ and a binds list containing *:* only).

They all use a timeout of five seconds, after which they give up.

snd <port> <arguments...>

Simply send a message to the given port - where you get the port ID from is your problem.

Exits after ensuring that the message has been delivered to its node.

Most useful to take avdantage of some undocumented functionality inside nodes, such as node ports being able to call any method:

aemp snd doomed AnyEvent::Watchdog::restart 1

rpc <port> <arg...>

Like aemp snd, but appends a local reply port to the message and waits for a message to it.

Any return values will be JSON-encoded and printed separated by commas (kind of like a JSON array without []-brackets).

Example: ask the (undocumented) time service of a node for it'S current time.

aemp rpc mynode time

mon <port>

Monitors the port and exits when it's monitorign callback is called. Most useful to monitor node ports.

Example: monitor some node.

aemp mon doomed

eval <node> <expr...>

Joins all remaining arguments into a string and evaluates it on the given node. Return values are handled as with aemp rpc.

Example: find the unix process ID of the node called posicks.

aemp eval posicks '$$'

trace <node>

Asks the given node for all currently connected nodes, then asks those nodes for the same, thus tracing all node connections.

CONFIGURATION/NODE ID/SECRET/CERTIFICATE

These commands deal with rather basic settings, the node ID, the shared secret and the TLS certificate.

setnodeid <nodeid>

Set the node ID to the given string.

delnodeid

Removes the node ID again, which means it is inherited again from it's parent profile, or stays unset.

gensecret

Generates a random shared secret and sets it. The shared secret is used to authenticate nodes to each other when TLS is not required.

setsecret <secret>

Sets the shared secret tot he given string, which can be anything.

delsecret

Removes the shared secret again, which means it is inherited again from it's parent profile, or stays unset.

gencert

Generates a self-signed certficate and key, and sets it. This works similarly to a shared secret: when all nodes have it, TLS will be used to authenticate and encrypt all traffic.

setcert <file>

Set a node certificate (and optionally any CA certificates) from the given file. The file must contain the key, followed by the certificate, followed by any CA certificates you want to trust, all in PEM format.

See AnyEvent::TLS for some more details - this sets the cert and ca_cert options.

delcert

Removes the certificate(s) again, which means it is inherited again from it's parent profile, or stays unset.

CONFIGURATION/SEEDS

To discover the network you have to specify some seed addresses, which are basically host:port pairs where you expect some long-running nodes. It does no harm to have a node as its own seed (they will eventually be ignored).

setseeds <host:port>,...

Sets or replaces the list of seeds, which must be specified as a comma-separated list of host:port pairs. The host can be a hostname, an IP address, or * to signify all local host addresses. If the :port is omitted, then the default port of 4040 is assumed.

An empty list is allowed.

Example: use doomed with default port as only seednode.

aemp setseeds doomed

delseeds

Removes the seed list again, which means it is inherited again from it's parent profile, or stays unset.

addseed <host:port>

Adds a single seed address.

delseed <host:port>

Deletes the given seed address, if it exists.

CONFIGURATION/BINDS

To be able to be reached from other nodes, a node must bind itself to some listening socket(s). The list of these can either bs specified manually, or AnyEvent::MP can guess them. Nodes without any binds are possible to some extent.

setbinds <host:port>,...

Sets the list of bind addresses explicitly - see the aemp setseeds command for the exact syntax. In addition, a value of 0 for the port means to use a dynamically-assigned port.

Note that the *, *:* or *:port values are very useful here.

Example: bind on the default port (4040) on all local interfaces.

aemp setbinds "*"

Example: bind on a random port on all local interfaces.

aemp setbinds "*:*"

Example: resolve "doomed.mydomain" and try to bind on port 4040 of all IP addressess returned.

aep setbinds doomed.mydomain

delbinds

Removes the bind list again, which means it is inherited again from it's parent profile, or stays unset.

addbind <host:port>

Adds a single bind address.

delbind <host:port>

Deletes the given bind address, if it exists.

CONFIGURATION/SERVICES

Services are modules (or functions) that are automatically loaded (or executed) when a node starts. They are especially useful when used in conjunction with aemp run, to configure which services a node should run.

setservices <initfunc>...

Sets or replaces the list of services, which must be specified as a comma-separated list.

Each entry in the list is interpreted as either a module name to load (when it ends with ::) or a function to call (all other cases). The algorithm to find the function is the same as used for AnyEvent::MP::spawn.

delservices

Removes the service list again, which means it is inherited again from it's parent profile, or stays unset.

addservice <initfunc>

Adds a single service.

delservice <initfunc>

Deletes the given service, if it exists.

CONFIGURATION/PROFILE MANAGEMENT

All the above configuration functions by default affect the global default configuration, which is basically used to augment every profile and node configuration.

profile <name> ...

This subcommand makes the following subcommands act only on a specific named profile, instead of on the global default. The profile is created if necessary.

Example: create a server profile, give it a random node name, some seed nodes and bind it on an unspecified port on all local interfaces. You should add some services then and run the node...

aemp server setnodeid anon/ setseeds doomed,10.0.0.2:5000 setbinds "*:*"

delprofile <name>

Deletes the profile of the given name.

setparent <name>

Sets the parent profile to use - values not specified in a profile will be taken from the parent profile (even recursively, with the global default config being the default parent). This is useful to configure profile classes and then to inherit from them for individual nodes.

Note that you can specify circular parent chains and even a parent for the global configuration. Neither will do you any good, however.

Example: inherit all values not specified in the doomed profile from the server profile.

aemp profile doomed setparent server

delparent

Removes the parent again from the profile, if any was set, so the profile inherits directly from the global default config again.

showprofile <name>

Shows the values of the given profile, and only those, no inherited values.

showconfig <name> <key value...>

Shows the effective config, i.e. the values as used by a node started with the given profile name. Any additional key-value pairs specified augment the configuration, just as with configure.

If all arguments are omitted, show the global default config.

cpanm AnyEvent::MP

perl -MCPAN -e shell
install AnyEvent::MP