/ 
AnyEvent-MP-1.1
River stage one • 2 direct dependents • 2 total dependents
/ aemp

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 cal <port> <arg...>      # send message, append reply
aemp eval <node> <expr...>    # evaluate expression
aemp trace <node>             # trace the network topology

# run a node
aemp run configure_args...    # run a node
aemp restart <node>           # restart a node if running under watchdog

# 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.

All configuration data is stored in a human-readable (JSON) config file stored in ~/.perl-anyevent-mp (or %appdata%/perl-anyevent-mp on loser systems). Feel free to look at it or edit it, the format is relatively simple.

SPECIFYING ARGUMENTS

Arguments can be specified just as with any other shell command, with a few special cases:

If the first argument starts with a literal [-character, then it is interpreted as a UTF-8 encoded JSON text. The resulting array replaces all arguments.

Otherwise, if any argument starts with one of [, { or ", then it is interpreted as UTF-8 encoded JSON text (or a single value in case of "), and the resulting reference or scalar replaces the argument.

This allows you, for example, to specify binds in aemp run (using POSIX shell syntax):

aemp run binds '["*:4040"]'

RUNNING A NODE

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

run <configure_args>...

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). A very common invocation is to just specify a profile using the profile name

aemp run database-backend

... but you can use most arguments that configure understands:

aemp run nodeid mynode2 profile someprofile

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.

restart <node>

Restarts the node using AnyEvent::Watchdog::Util::restart. This works for nodes started by aemp run, but also for any other node that uses AnyEvent::Watchdog.

PROTOCOL COMMANDS

These commands actually communicate with other nodes. They all use a node profile name of aemp (specifying a default 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 advantage of some undocumented functionality inside nodes, such as node ports being able to call any method:

aemp snd doomed AnyEvent::Watchdog::restart 1
cal <port> <arg...>

Like aemp cal: 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 its current time.

aemp cal 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 cal.

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 certificate 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 (which makes little sense for seeds, outside some examples, but a lot of sense for binds).

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 * for the port, or not specifying a port, means to use a dynamically-assigned port.

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

Example: bind on a ephemeral port 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:4040
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 or a JSON array.

Each string 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).

Each entry which is an array itself (you need to use JSON format to specify those) is interpreted as a function name and the arguments to pass.

The algorithm to find the function is the same as used for AnyEvent::MP::spawn.

Example: run the globa service (which runs anyway, but this doesn't hurt).

aemp setservices AnyEvent::MP::Global::

Example: call the mymod::myfun function with arguments 1, 2 and 3.

aemp setservices '[["mymod::myfun", 1,2,3]]'
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 profile server nodeid anon/ seeds doomed,10.0.0.2:5000 binds "*:*"
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.