CONCEPT
erq - External Request Demon
DESCRIPTION
Up to version 3.2.1@61, LPMud utilized two external programs
in an ad-hoc manner to solve problems: the 'hname' program to
resolve IP addresses into meaningful hostnames, and the
'indent' program to properly indent LPC files. In version
3.2.1@61 both functions were united in a generalized 'erq'
process, to which additional functions may be attached.
Unfortunately it was never documented by Amylaar, so the
information presented here had to be reverse engineered
from the sources - better take it with a grain of salt.
The erq feature is available if the driver is compiled with
ERQ_DEMON defined (in config.h).
When the driver starts up, it tries to fork off the program
'BINDIR/erq --forked <other args>' (with BINDIR defined in
the Makefile). If this succeeds, the erq may talk with
the driver through stdin and stdout (piped through AF_UNIX
sockets). The erq has to signal its successfull start by
writing the character '1' back to the driver.
The erq has to understand these commandline arguments:
--forked: explained above
--execdir <dir>: The directory where the callable executables
can be found. If not specified, ERQ_DIR is used.
<dir> must not end in a '/' and should be absolute.
At runtime, the erq may be changed/removed from within the
mudlib using the efun attach_erq_demon(). This efun is given
an interactive object as argument, and takes the connection
away(!) from this object and stores it as the erq connection
to use (an old erq connection is closed first). The object
(which is now no longer is interactive) is then no longer
needed, but may continue to exist. The erq attached this way
of course has to use the sockets it opened to communicate
with the driver.
Most of the communication between erq and driver is going to
be initiated by the driver (the erq has to look up the
hostnames for given IP addresses), but using the efun
send_erq() the mudlib may talk with the erq as well.
The communication between driver and erq is done using
messages of specified structures and constants (defined in
util/erq.h resp. sys/erq.h). The 'int32's are signed integers
of four byte length, and are sent with the MSByte first.
Every message must be sent atomically!
The head of the messages is always the same:
struct erq_msghead {
int32 msglen; /* Total size of message in bytes */
int32 handle; /* Identification number */
}
The 'handle' number is set by the driver (do not make
assumptions about its value) and is used to associated the erq
responses with the pending requests. This way the erq is free
to respond in an order different to those of the incoming
requests.
The messages send to the erq follow this symbolic format:
struct to_erq_msg {
int32 msglen;
int32 handle;
char request;
char data[0];
}
The 'request' denotes which service is requested from the erq,
the size and content of 'data' depends on the requested
service.
The answer message from the erq to the driver (if there is one
at all) may have two forms:
struct from_erq_msg {
int32 msglen;
int32 handle;
char data[0];
}
struct from_erq_keep_msg {
int32 msglen;
const int32 keep = ERQ_KEEP_HANDLE;
int32 handle;
char data[0];
}
The replied data from the erq is stored in 'data', which size
and content depends on the request answered. The answer is
identified by 'header.handle'. Normally, one request results
in just one response sent by the erq using struct from_erq_msg,
so the handle is recycled after this response.
Shall the erq send several responses (or break one response
into several parts), the struct from_erq_keep_msg has to be
used for all but the last response - this message with its
included special handle keeps the real handle alive.
Mudlib generated erq-calls specify the 'request' and the
'data' to be sent, and receive the 'data' replied. When
dealing with spawned programs, the first byte of the returned
'data' determines the content type of the received message.
The actual 'data' which the lpc programs get to see is sent
and retrieved as arrays of byte integers (integers in the
range of 0..255).
The actual interface between erq demon and driver is limited
to the general message formats and the hostname lookup
mechanism. The driver is meant to withstand erq demon failures
at least in a garbage-in garbage-out fashion. You could add
new requests to the erq demon, or write your own from scratch,
without changing the driver.
Currently five services are predefined in the supplied
erq-demon (util/erq.c in the driver source archive): looking
up a hostname, execution, forking or spawning an external
program, authentification of a connection, and handling of
external UDP/TCP connections. As mentioned above, only the
hostname-lookup is a true must.
For a program to be executable for erq, it must be placed in
or below ERQ_DIR (defined in config.h). On most unix systems,
it is possible to use a symlink instead of the whole program
if you want a standard binary. You could even symlink entire
directories like /usr/sbin, but chances are you make a big
security hole this way :-)
Hostname lookup:
request : ERQ_RLOOKUP
data sent: struct in_addr.s_addr addr // the address to resolve
data recv: struct in_addr.s_addr addr // the resolved address
char[] name // the hostname (if any)
If the sent address can't be resolved, just the address is
to be returned. The string need not be 0-terminated.
Hostname lookup:
request : ERQ_LOOKUP
data sent: char[] name // the name to resolve
data recv: struct in_addr.s_addr addr // the resolved address
If the sent address can't be resolved, no data is returned (the
driver will get a message with just the header).
Hostname lookup - IPv6:
request : ERQ_RLOOKUPV6
data sent: char[] addr // the address to resolve
data recv: char[] data // the resolved name
If the address could be resolved, the returned data is a string,
with exactly one space, in the form "<addr> <name>". <addr> is
the address passed to the erq, <name> is the hostname of the
address or, if there is no reverse-IPv6 entry for <addr>, the
IPv6 address which may or may not be different from <addr>.
If the address can not be resolved, the returned data is
an error message without a space (currently, just "invalid-format"
and "out-of-memory" are returned).
Execute/Fork program:
request : ERQ_EXECUTE/ERQ_FORK
data sent: char[] command // the command to execute
data recv: char status = CHILD_FREE
char rc // the success/error code
char info // additional information
The erq executes the sent command using the execv().
The erq does the processing of the command line arguments
(which must not contain '\') and checks the validity of the
command (it must not start with '/' nor contain '..'), which
is interpreted relative to ERQ_DIR.
The external program is executed from a fork()ed instance of
the erq, however, with ERQ_EXECUTE the erq waits until the
external program finished before replying its response, with
ERQ_FORK the response is immediately sent back.
Possible return codes are:
ERQ_OK : Operation succeeded.
ERQ_E_ARGLENGTH: Too long command.
ERQ_E_ARGFORMAT: Illegal argument given (contains '\');
ERQ_E_ARGNUMBER: Too much arguments (>= 96).
ERQ_E_ILLEGAL : Command from outside ERQ_DIR requested.
ERQ_E_PATHLEN : Commandpath too long.
ERQ_E_FORKFAIL : Command could not be forked;
info holds the errno value.
ERQ_EXECUTE features some more return codes:
ERQ_OK : Operation succeeded, <info> holds the exit status.
ERQ_SIGNALED : Command terminated the signal <info>.
ERQ_E_NOTFOUND : No process found to wait() for.
ERQ_E_UNKNOWN : Unknown exit condition from wait().
Spawn program:
request : ERQ_SPAWN
data sent: char[] command // the command to execute
data recv: Spawn failed:
char rc // the error code (see ERQ_FORK)
char info // additional information
data recv: Spawn succeeded:
char rc = ERQ_OK
char[] ticket // the spawn ticket.
The erq executes the sent command as if given an ERQ_FORK
command, but returns additional information about the
started process to allow further communication.
In contrast to ERQ_FORK, ERQ_SPAWNED processes may be
controlled via ERQ_KILL, receive data from the mud via
ERQ_SEND on their stdin, and output from their stdout/stderr
is sent back to the mud.
The spawned process is identified by its <ticket> (don't
make any assumptions about its length or content), the transaction
itself by <handle>.
Send data to spawned program:
request : ERQ_SEND
data sent: char[] ticket // the addressed process ticket.
char[] text // the text to send.
data recv: char rc // the success/error code.
int32 info // opt: additional info.
The <text> is sent to the stdin of the spawned process
identified by <ticket>.
Possible return codes are:
ERQ_OK : Operation succeeded, no <info> is replied.
ERQ_E_TICKET : The given ticket is invalid, no <info> replied.
ERQ_E_INCOMPLETE: Only <info> chars of the text have been
sent.
If a callback is specified, the erq will send
a ERQ_OK message once all data has been sent
(this may never happen).
ERQ_E_WOULDBLOCK: Error E_WOULDBLOCK (also stored in <info>)
happened while sending the text.
ERQ_E_PIPE : Error E_PIPE (also stored in <info>)
happened while sending the text.
ERQ_E_UNKNOWN : The error with code <info> happened
while sending the data.
Amylaar-erq doesn't try to re-send the remaining data after
a ERQ_E_INCOMPLETE, so there will never be an ERQ_OK.
Send a signal to a spawned program:
request : ERQ_KILL
data sent: char[] ticket // the addressed process ticket
int32 signal // the signal to send
data recv: char rc // the success/error code
The <signal> is sent to the spawned process identified by <ticket>.
Possible return codes are:
ERQ_OK : Operation succeeded, no <info> is replied.
ERQ_E_TICKET : The given ticket is invalid, no <info> replied.
ERQ_E_ILLEGAL : The given signal is illegal.
Data replies from spawned programs:
data recv: char out_or_err // type of text output
char[] text // text output by child process
The child process controlled by the erq did output <text>
on stdout (<out_or_err> == ERQ_STDOUT) resp. on stderr
(<out_or_err> == ERQ_STDERR).
Exit notifications from spawned programs:
data recv: char rc // the exit code
char info // additional information.
The child process controlled by the erq did terminate.
Possible exit codes are:
ERQ_EXITED : Process exited with status <info>.
ERQ_SIGNALED : Process terminated by signal <info>.
ERQ_E_UNKNOWN : Process terminated for unknown reason.
Authenticate connection (see rfc 931):
request : ERQ_AUTH
data sent: struct sockaddr_in remote // the address to check
int32 port // the mud port
or
data sent: int32 remote_ip // remote ip to check
int16 remote_port // remote port to check
int16 local_port // the mud port
data recv: char[] reply // the data received by authd
The erq attempts to connect the authd on the remote system
and to verify the connection between the remote port and the
mud port. The latter will normally be the port number of the
socket on besides of the gamedriver, retrievable by
query_ip_number().
The answer from the authd (one line of text) if there is any
is returned as result.
The second form of the ERQ_AUTH command is recognized by
the xerq as alternative.
Open an UDP port:
request : ERQ_OPEN_UDP
data sent: char[2] port // the port number to open (network order)
data recv: Open failed:
char rc // the success/error code.
char info // opt: additional info.
data recv: Open succeeded:
char rc = ERQ_OK
char[] ticket // the connection ticket.
The erq opens an UDP-port on the host machine with the given
port number.
Possible exit codes are:
ERQ_OK : Operation succeeded.
ERQ_E_ARGLENGTH : The port number given does not consist
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
spawned program.
Send data over an UDP port:
request : ERQ_SEND
data sent: char[] ticket // the addressed port's ticket.
struct in_addr.s_addr addr // address of receiver.
struct addr.sin_port port // port of receiver.
char[] text // the text to send.
data recv: char rc // the success/error code.
int32 info // opt: additional info.
The <text> is sent from our port <ticket> to the network
address <addr>, port <port>.
Possible return codes are:
ERQ_OK : Operation succeeded, no <info> is replied.
ERQ_E_TICKET : The given ticket is invalid, no <info> replied.
ERQ_E_INCOMPLETE: Only <info> chars of the text have been
sent. The erq will send a ERQ_OK message
once all data has been sent.
ERQ_E_WOULDBLOCK: Error E_WOULDBLOCK (also stored in <info>)
happened while sending the text.
ERQ_E_PIPE : Error E_PIPE (also stored in <info>)
happened while sending the text.
ERQ_E_UNKNOWN : The error with code <info> happened
while sending the data.
Close an UDP port:
request : ERQ_KILL
data sent: char[] ticket // the addressed port's ticket
int32 signal // the signal to send (ignored)
data recv: char rc = ERQ_OK
The port <ticket> is closed. The <signal> must be sent, but
its value is ignored.
Data received over an UDP connection:
data recv: char out_or_err = ERQ_STDOUT
struct in_addr.s_addr addr // ip-address of sender
struct addr.sin_port port // port of sender
char[] text // data received
The UPD port controlled by the erq did receive <text> over
the network from the sender at <addr>, reply port number <port>.
Open a TCP port to listen for connections:
request : ERQ_LISTEN
data sent: struct addr.sin_port port // the port number to open
data recv: Open failed:
char rc // the success/error code.
char info // opt: additional info.
data recv: Open succeeded:
char rc = ERQ_OK
char[] ticket // the connection ticket.
The erq opens a TCP-port on the host machine with the given
port number to listen for connections.
Possible exit codes are:
ERQ_OK : Operation succeeded.
ERQ_E_ARGLENGTH : The port number given does not consist
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
spawned program.
Open a TCP port:
request : ERQ_OPEN_TCP
data sent: struct in_addr.s_addr ip // the ip to address
struct addr.sin_port port // the port to address
data recv: Open failed:
char rc // the success/error code.
char info // opt: additional info.
data recv: Open succeeded:
char rc = ERQ_OK
char[] ticket // the connection ticket.
The erq opens a TCP-port on the host machine and tries to connect
it to the address <ip>:<port>.
Possible exit codes are:
ERQ_OK : Operation succeeded.
ERQ_E_ARGLENGTH : The port number given does not consist
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
spawned program.
Send data over a TCP connection:
request : ERQ_SEND
data sent: char[] ticket // the addressed process ticket.
char[] text // the text to send.
data recv: char rc // the success/error code.
int32 info // opt: additional info.
The <text> is sent to the stdin of the spawned process
identified by <ticket>.
Possible return codes are:
ERQ_OK : Operation succeeded, no <info> is replied.
ERQ_E_TICKET : The given ticket is invalid, no <info> replied.
ERQ_E_INCOMPLETE: Only <info> chars of the text have been
sent. The erq will send a ERQ_OK message
once all data has been sent.
ERQ_E_WOULDBLOCK: Error E_WOULDBLOCK (also stored in <info>)
happened while sending the text.
ERQ_E_PIPE : Error E_PIPE (also stored in <info>)
happened while sending the text.
ERQ_E_UNKNOWN : The error with code <info> happened
while sending the data.
Data ready to read on TCP connection:
data recv: char out_or_err = ERQ_OK
char[] ticket // ticket of this connection
There is data available to read on the specified TCP connection.
Data received over a TCP connection:
data recv: char out_or_err = ERQ_STDOUT
char[] text // data received
The TCP port controlled by the erq did receive <text>.
TCP connection closes on error:
data recv: char out_or_err = ERQ_E_UNKNOWN
char errno // errno from socket operation
The TCP connection caused an error <errno> and has been closed.
TCP connection closed:
data recv: char out_or_err = ERQ_EXITED
The TCP connection closed regularily (End Of File).
Connection pending on TCP socket:
data recv: char out_or_err = ERQ_STDOUT
The TCP 'listen' port controlled by the erq received
a connection request.
Accept a pending connections:
request : ERQ_ACCEPT
data sent: char[] ticket // the ticket of this socket
data recv: Accept failed:
char rc // the success/error code.
char info // opt: additional info.
data recv: Accept succeeded:
char rc = ERQ_OK
struct in_addr.s_addr ip // remote side's ip
struct addr.sin_port port // remote side's port
char[] ticket // the new ticket.
The erq accepts a new connection on an accept-TCP-port, creates
a child and ticket for it, and returns its ticket together with
the remote's side <ip>:<port> number (in network byte order).
Possible exit codes are:
ERQ_OK : Operation succeeded.
ERQ_E_ARGLENGTH : The port number given does not consist
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
ERQ_E_TICKET : the ticket didn't match
ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if it is just another
spawned program.
EXAMPLE
Assume you have a script 'welcome-mail' to send a welcome mail
to a new player. Put this script into the directory for the callable
executables, then you can use it like this:
void erq_response(mixed * data)
{
write_file( "WELCOMELOG"
, sprintf("rc %d, info %d\n", data[0], data[1]));
}
void send_mail(string player_name, string player_email)
{
send_erq( ERQ_EXECUTE
, "welcome-mail '"+player_name+"' '"+player_email+"'"
, #'erq_response);
}
HISTORY
The erq was introduced with 3.2.1@61.
ERQ_AUTH was introduced with 3.2.1@81.
ERQ_SEND, ERQ_SPAWN, ERQ_KILL were introduced with 3.2.1@82.
ERQ_OPEN_UDP, ERQ_OPEN_TCP, ERQ_LIST were introduced with 3.2.1@98.
ERQ_RLOOKUPV6 was introduced in 3.2.8.
LDMud 3.2.9 added the '--execdir' argument to erq, and the ERQ_OK
after ERQ_E_INCOMPLETE protocol.
SEE ALSO
attach_erq_demon(E), send_erq(E), stale_erq(M), rfc 931
query_ip_number(E)
|
