ipsvd-instruct(5)

✨ ipsvd-instruct(5) ✨

ok bestie, welcome to the File Formats Manual, section 5 — this one's all about the format of the ipsvd(8) instructions directory. no cap, it's giving very "small file, huge power" energy. 🎀

---

🌸 NAME 🌸

ipsvd-instruct — the format of the ipsvd(8) instructions directory

---

💅 DESCRIPTION 💅

so the internet protocol service daemons, ipsvd(7), can be told to read and follow instructions from a directory whenever a connection comes in on the socket they're listening on. like, a little folder of vibes that decides what happens. 🗂️

and for mostly static instructions — or just for performance reasons — you can compile the instructions from a directory into a constant database (cdb) with ipsvd-cdb(8) for faster lookup, and then tell ipsvd(7) to read the instructions from there instead. glow up via precompilation, honestly. ⚡

---

🦋 MATCHING 🦋

on each incoming connection, ipsvd(7) matches the client's IP address against files in the instructions directory. example time: the IP address a.b.c.d, which reverse resolves to moa.bit.smarden.org, gets matched against the following files in the instructions directory, in this order — and first match wins, periodt:

1. a.b.c.d
2. a.b.c
3. a.b
4. a

and 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) examines the file that matched 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. bye. 👋
2. if the file has the user's execute permission set, ipsvd(7) reads the contents of the file and runs /bin/sh -c '<contents>' 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) reads the contents of the file and interprets each line as an instruction for this connection (more on that below 👇).

and 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. no drama. 💜

---

👑 INSTRUCTIONS 👑

if ipsvd(7) is given instructions for an incoming connection, it reads the corresponding file and interprets each line like this. the file may be empty, meaning that there is no special instruction. (empty file = chill, no notes. 💀)

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) 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) makes sure that the environment variable with the name string is not set.
• Cnum[: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, the 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)'s support per host concurrency. 🙈

• =hostname[:forward] — check hostname. if the line starts with a =, and is followed by a hostname, ipsvd(7) 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) stops processing the instructions here and runs prog. if hostname is followed by a colon and forward, ipsvd(7) 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. bestie, that's a real wait. 😭

if ipsvd(7) cannot interpret a line, it prints a warning, discards the line, and continues with the next instruction if any. (graceful. we love to see it. 💅)

after processing all instructions, ipsvd(7) runs prog. but 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 instruction 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-cdb(8), tcpsvd(8), sslsvd(8), udpsvd(8), sslio(8)

http://smarden.org/ipsvd/

---

⭐ AUTHOR ⭐

Gerrit Pape <pape@smarden.org>

---

and that's the whole page, bestie — straight out of the ipsvd-instruct(5) manual page in the File Formats Manual, no details dropped, all facts intact, only the vibes were upgraded. 💖✨ slay responsibly, and go read your instructions directory like the main character you are. 🎀🦋💜