--- name: "ipsvd-instruct" section: "5" platform: "linux" package: "ipsvd" version: "1.0.0-12" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ipsvd-instruct" --- # ipsvd-instruct(5) format of the ipsvd(8) instructions directory ## NAME ipsvd-instruct - format of the ipsvd(8) instructions directory ## DESCRIPTION The internet protocol service daemons, [**ipsvd**(7)](/ipsvd/7.md), can be told to read and follow instructions from a directory on incoming connections to the socket they listen on. For mostly static instructions or for performance reasons, it is possible to compile the instructions from a directory into a constant database (cdb) with [**ipsvd-cdb**(8)](/ipsvd-cdb/8.md) for faster lookup, and to tell [**ipsvd**(7)](/ipsvd/7.md) to read the instructions from there. ## MATCHING On each incoming connection, the [**ipsvd**(7)](/ipsvd/7.md) matches the client's IP address against files in the instructions directory. For example, the IP address *a.b.c.d* which reverse resolves to *moa.bit.smarden.org* is matched against the following files in the instructions directory, in this order, first match wins: - 1\. *a.b.c.d* - 2\. *a.b.c* - 3\. *a.b* - 4\. *a* If the client's hostname has been successfully looked up in DNS: - 5\. *moa.bit.smarden.org* - 6\. *bit.smarden.org* - 7\. *smarden.org* - 8\. *org* And finally the catchall file \`\`0'' (zero): - 9\. *0* After successfully matching a client's IP address or hostname against the instructions directory, [**ipsvd**(7)](/ipsvd/7.md) examines the file that matched the IP address or hostname, and acts accordingly: - 1\. If neither the user's read permission, nor the user's execute permission is set for the file, the connection is closed immediately. - 2\. If the file has the user's execute permission set, [**ipsvd**(7)](/ipsvd/7.md) reads the contents of the file and runs */bin/sh -c '\'* instead of the default program *prog* given at the command line for this connection. - 3\. If the file has the user's read permission set, [**ipsvd**(7)](/ipsvd/7.md) reads the contents of the file and interprets each line as an instruction for this connection (see below). If the client's IP address or hostname doesn't match any file in the instructions directory, the default action is taken (the program *prog* is run to handle the connection). ## INSTRUCTIONS If [**ipsvd**(7)](/ipsvd/7.md) is given instructions for an incoming connection, it reads the corresponding file and interprets each line as follows. The file may be empty, meaning that there is no special instruction. Empty lines and lines starting with \`\`#'' are ignored. - **+***VAR=VALUE* environment. If the line starts with a plus (\`\`+''), and the string following the plus contains a \`\`='', [**ipsvd**(7)](/ipsvd/7.md) puts the string following the plus into the environment before starting *prog* to handle the connection. If the string following the plus doesn't contain a \`\`='', [**ipsvd**(7)](/ipsvd/7.md) makes sure that the environment variable with the name string is not set. - **C***num\[:msg\]* concurrency. If the line starts with a \`\`C'', and is followed by a number, the per host concurrency limit for the IP address that initiated the connection is set to this number. If *num* is zero, per host concurrency limit is disabled. If *num* is followed by \`\`:*msg'',* the message *msg* is written to this client if possible, if the per host concurrency limit is reached. *msg* may contain backslash-escaped characters as follows: \`\`\\\\'' is converted to a single backslash, \`\`\\n'' is converted to a new line character, and \`\`\\r'' is converted to a carriage return. On multiple concurrency instructions the last processed concurrency instruction is considered. Not all [**ipsvd**(7)](/ipsvd/7.md)'s support per host concurrency. - **=***hostname\[:forward\]* check hostname. If the line starts with a \`\`='', and is followed by a hostname, [**ipsvd**(7)](/ipsvd/7.md) looks up the IP addresses for *hostname* in DNS and checks if the client's IP address matches one of these IP addresses. If so, [*ipsvd*(7)](/ipsvd/7.md) stops processing the instructions here and runs *prog*. If *hostname* is followed a colon and *forward*, [**ipsvd**(7)](/ipsvd/7.md) now examines the file *forward* and acts accordingly, instead of running *prog*. All check hostname instructions in *forward* are ignored. If *forward* does not exist, the connection is closed. *hostname* may be \`\`0'' (zero), matching any IP address. Note: Using check hostname instructions can cause significant delay while responding to connection attempts, caused by DNS lookups. If [**ipsvd**(7)](/ipsvd/7.md) cannot interpret a line, it prints a warning, discards the line, and continues with the next instruction if any. After processing all instructions, [**ipsvd**(7)](/ipsvd/7.md) runs *prog*. If the file contains at least one check hostname instruction, and none was successful, it closes the connection instead of running *prog*. ## EXAMPLE INSTRUCTIONS - \+MEMORY=20000 This instruction causes the environment variable \`\`MEMORY'' with the value \`\`20000'' to be available to the program *prog* that handles the connection. - \+DEBUG= This instruction adds the variable \`\`DEBUG'' with an empty value to the environment. - \+LOGNAME This instructions makes sure that the environment variable \`\`LOGNAME'' is unset when running *prog*. - C16 Set the per host concurrency to 16. A connection will be closed silently if there are already 16 active connections from this client's IP address. - \=floyd.dyn.smarden.org:127.0.0.1 Check IP address of the dynamic hostname *floyd.dyn.smarden.org*. If one of the IP addresses *floyd.dyn.smarden.org* currently resolves to matches the client's IP address, handle the connection through the file *127.0.0.1* in the instructions directory. ## SEE ALSO [ipsvd(7)](/ipsvd/7.md), [ipsvd-cdb(8)](/ipsvd-cdb/8.md), [tcpsvd(8)](/tcpsvd/8.md), [sslsvd(8)](/sslsvd/8.md), [udpsvd(8)](/udpsvd/8.md), [sslio(8)](/sslio/8.md) http://smarden.org/ipsvd/ ## AUTHOR Gerrit Pape \