Pour activer ce module, il doit être compilé et chargé via la configuration de votre instance httpd courante, et les directives ci-dessous permettent de sélectionner les données que vous souhaitez enregistrer.

Il est possible d'enregistrer les données entrantes et sortantes dans le même fichier, car la direction du flux est indiquée dans chaque fragment.

Il est possible d'écrire vers des fichiers normaux ou des listes fifos (pipes). Dans le cas des listes fifos, mod_firehose fait en sorte que la taille des paquets ne dépasse pas la valeur de PIPE_BUF afin de s'assurer que l'écriture de ces derniers s'effectue en une seule fois.

Si une liste fifo sous forme de pipe doit être utilisée, pour que cette dernière soit ouverte en écriture, certaines données doivent en être extraites avant le démarrage de httpd. Si l'ouverture du pipe échoue, mod_firehose ne sera pas activé, et le serveur sera lancé normalement.

Par défaut, toute tentative d'écriture bloque le serveur. Si le serveur a été compilé avec APR version 2.0 ou supérieure, et si le paramètre "nonblock" a été spécifié, les écritures dans les fichiers seront non blocantes, et tout dépassement de tampon entraînera la perte des données de débogage. Dans ce cas, il est possible donner la priorité à l'exécution du serveur sur l'enregistrement des données firehose.

En général, le serveur gère plusieurs connexions simultanément, et de ce fait, les requêtes et les réponses doivent être multiplexées avant d'être écrites dans le firehose.

Chaque fragment se présente sous la forme d'un texte en clair de façon à ce qu'un firehose puisse être ouvert et inspecté par un éditeur de texte standard. Il est aussi possible d'utiliser l'utilitaire firehose pour démultiplexer le firehose en requêtes ou connexions individuelles.

La taille maximale des fragments multiplexés est définie par la variable PIPE_BUF. Elle correspond à la taille maximale d'un élément que le système peut écrire. Si la taille des fragments multiplexés reste en dessous de PIPE_BUF, le module garantit que les contenus des différents fragments ne se recouperont pas. La valeur de PIPE_BUF varie en fonction du système d'exploitation.

La BNF du format du fragment est la suivante :

 stream = 0*(fragment)

 fragment = header CRLF body CRLF

 header = length SPC timestamp SPC ( request | response ) SPC uuid SPC count

 length = <longueur de fragment sur 16 octets hexadécimaux>
 timestamp = <temps depuis 1970 en microsecondes sur 16 octets hexadécimaux>
 request = "<"
 response = ">"
 uuid = <uuid formaté de la connexion>
 count = <numéro hexadécimal du fragment dans la connexion>

 body = <contenu binaire du fragment>

 SPC = <un espace>
 CRLF = <un retour chariot suivi d'une nouvelle ligne>
    

Tous les fragments d'une connexion ou d'une requête partagent le même UUID, selon que les connexions ou les requêtes sont enregistrées ou non. Si les connexions sont enregistrées, plusieurs requêtes peuvent apparaître dans la même connexion. Un fragment de longueur nulle indique la fin de la connexion.

Certains fragments peuvent manquer ou être supprimés si le processus qui les lit est trop lent. Si cela se produit, il y aura des trous dans le comptage des connections. Un avertissement indiquant l'UUID et le numéro du fragment supprimé sera enregistré dans le journal des erreurs.

En cas de crash ou d'arrêt forcé du processus httpd, il est possible que le fragment vide de terminaison n'apparaisse pas. Cela peut aussi se produire si le processus qui lit les fragments n'est pas assez rapide.