+- HostServ
 +- ProcServ
 '- kino.mod

 `- GSP

 +- Disklaimer
 `- Links

Requirements / Limitations

ProcServ is an irc service and provides ProcServ tasks as well as interaction with ProcServ tasks in an irc enviroment. (ProcServ tasks are processes started by ProcServ which have got an irc representant.)
Administration of ProcServ and starting of ProcServ tasks is done via the 'Manager'. He gets introduced to the irc network by ProcServ and his resources are limited to authenticated users.
ProcServ task controllation is virtually outsourced to process representans in irc. This means every process gets its own and unique nick first and virtually connects to the host where procserv is running then. Finally an authenticated user is enabled to do interprocess communication with the process via the ProcServ task which is limited to :

emit SIGTERM - equivalent to " STRG+C "
emit SIGHUP - equivalent to " kill -HUP pid "
emit SIGKILL - equivalent to " kill -KILL pid "
send strings to std in - equivalent to write strings inclusive carriage return in a shell while a process is running

ProcServ configuration is based on a monolithic file in xml format. Its entities will be described in Configuration.

  Requirements / Limitations
Currently only Hybrid and Bahamut based ircds are supported by ProcServ.
To get build ProcServ depends on an CommonC++ installation. Unless you want to edit code from ProcServ i suggest you to install CommonC++'s headers into /usr/include/cc++ or /usr/local/include/cc++. Because this library is from GNU and supported by many plattforms I except no difficulties concerning this.
Furthermore ProcServ has been designed for using the LINUX API. Therefore I do not know if ProcServ can be compiled on *BSD plattforms.
Last but not least I expect from the configurator that he or she knows about the limitations implemented by the used ircd ! Extensive valuechecking is not implemented (yet) by ProcServ.

As already mentioned ProcServ differs between Manager and ProcServ tasks. So we do now:

Available commands for the Manager:
Command Description
auth This command is used to gain access to ProcServ and expects 2 arguments: a valid login name and it's respective password. If both do not match an error will be printed.
deauth This command does the opposite of what auth does and expects no argument. In case of no error procserv prints, that deauth was successfully.
add This command is preserved for authed users.
This Command expects at least one argument which sets the name of the ProcServ task which should be executed. You can add more arguments to this command which will be treated as arguments for the process. If the first argument starts with an '+' procserv will interpretate this character as an argument-concatenation operator which results in. If this feature should be disabled put a '\' in front of the string.
If no Process Task for this name could be found an error message will be displayed.
sysinfo This command is preserved for authed users.
This command expects no argument(s) and simply prints statistic data about the enviroment ProcServ is running in.
rehash This command is preserved for authed users.
This command expects no argument(s) and lets ProcServ re-read the configuration file.
listvprogs This command is preserved for authed users.
This command expects no argument and lets you view the name of every available ProcServ task as well as its respective data.

Available commands for a ProcServ task:
Command Description
comm Communicate with this ProcServ task. Expects at least one argument. This argument will be send to the process running in the background in the same manner as if a user would have typed this at the console where the process is running.
hup This is one of the IPC features ProcServ offers as already mentioned before.
This command expects no additional argument as it will just send a SIGHUP to the ProcServ task.
del This is another command to signal a the ProcServ task virtually.
Sends SIGTERM to the process behind the ProcServ task which is equivalent to STRG+C on console.
Expects no argument.
kill This will make ProcServ send SIGKILL to the process behind the ProcServ task and should make the process stop immediately.
Expects no argument also.

ProcServ configuration begins at build time. The file config.h in the directory include/ contains some #define s which have to be edited or maybe ProcServ won't be able to communicate with your irc server.
The defines are already documented in config.h but to be sure having mentioned all configuration abilities here i will list every define:
#define Description
XMLFILE sets the default path and filename to the procserv configuration file in XML format. Non-full-qualified paths are allowed though but i recommend you to use a full-qualified path to ensure it does not matter from where procserv got started.
DEBUG This feature is used by (the) developer(s) to debug ProcServ. If you wish to get extended information on what ProcServ is doing #define this. Else I recommend you not to use this define.
VERBOSE_MEMORY Is used to do basic memory profiling. Else you are not a developer I recommend you not to define VERBOSE_MEMORY.
DEBUG_XML Another define to enable ProcServ debugging. This options will make ProcServ _really_ verbose on startup. Do not define DEBUG_XML.
SERVER_TYPE This #define is mandatory as it sets the way ProcServ will communicate with your used irc server.
Valid value are #defined in config.h:
* - ProcServ does not support this feature currently.

Real procserv configuration is done through a file as defined with XMLFILE . Its format bases on XML. The entities and what they set will be described yet:

The ProcServ configuration file must contain only one entity named ProcServ and has got 3 subentities named "IRC", "Processes" and "Auth":
  <IRC >
  </IRC >



    Entity IRC

The entity "IRC" has got 3 subentities named "Remote", "Local" and "Manager".
Entity "Remote" sets values important for the connection to an irc hub where ProcServ should connect to.
"Server" sets the dns name or ip of the server which ProcServ should connect.
"Port" is an integer and sets the port which should be connected.
"Password" is the connect password which will be used after an successfull connect.

The following entity sets values which will be used when procserv introduces itself to the irc network.
  <Hostname> </Hostname>
  <ServerDescription >ProcServ - process server<ServerDescription>
"Hostname" sets the server name which will be used to identify procserv in the irc network.
"ServerDescription" sets the server description.

The "Manager" entity includes the values for the ProcServ manager:
  <Nick> </Nick>
  <Ident> </Ident>
  <Address> </Address>
  <Realname> </Realname>
  <Modes> </Modes>
"Nick" sets the manager nick. Maybe you want to make this nick only available for ircops with an Q:line.
"Ident" sets the virtual ident for the Manager.
"Address" sets the virtual address for the Manager.
"Realname" sets the realname used for the Manager.
"Modes" sets the user modes ProcServ.
Warning: this values are not checked against limitations implemented by the irc server. Means if the maximum nicklength is 9 and you have set an Manager nick with 10 ore more characters procserv will not correct your values. Furthermore ProcServ should not work properly as he uses the nicknames to differ between ProcServ tasks and the Manager and the real Managernickname differs from the intern nickname!
!! I expect from the ProcServ user that he or she has got enough experiences made with his his / her favourite ircd to configure ProcServ correctly !!

    Entity Processes

The "Processes" entity must not have any subentities of type "Process" but in generally it is a good idea to define virtual processes or ProcServ will be rather useless :-) .
At least this declaration is mandatory or ProcServ will refuse to start.

Additionally one can write:

    <IRCIdent >irc-ident </IRCIdent>
    <IRCModes >irc-usermodes</IRCModes>
    <IRCChannel>irc-channel </IRCChannel>
There is no limitation on how many "Process" entities may defined.
A "Process" entity describes a ProcServ task. "ID" sets the identifier string for this ProcServ task and may not contain any white spaces. ID must be unique!
"Command" sets the name of the executeable which is connected to "ID".
"Options" will be given as an argument to the executeable.
"ID", "Command" and "Options" declarations are mandatory in contrast to the "IRC*" declarations. If not defined their value will be used from fall-back values. I think the names of the IRC* declarations are self-explanatory. Their values oblige the same irc server limitations as mentioned above.
With the "Default*" declarations in entity "Processes" the fall-back values can be set. But these declarations are not mandatory though it makes sense to include them in your own procserv.xml configfile.

    Entity Auth

This entity is used to set logins. I recomm you to define some logins here or you wont be able to use ProcServ really :-) . A typical Auth entity would look like this:




"Name" sets the favoured login name. This one should be unique and may not contain any whitespaces.
The same for "Password". There are no limitations on the string length It is generally a good idea to use ascii characters only as unicode is not supported by procserv (yet).
This entity is mandatory as well as "Processes" and "IRC" are.

An example how a procserv configurationfile could look like is included within the procserv package. One can find it in the subdirectory 'etc/' and is named "procserv.xml".

Drink more tabasco.

© Martin Scholl
Last modified: Fri Jan 4 00:36:41 CET 2002