contrib/unbound/dnstap/dnstap.h

   1 /* dnstap support for Unbound */
   2
   3 /*
   4  * Copyright (c) 2013-2014, Farsight Security, Inc.
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright
  12  * notice, this list of conditions and the following disclaimer.
  13  *
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  * notice, this list of conditions and the following disclaimer in the
  16  * documentation and/or other materials provided with the distribution.
  17  *
  18  * 3. Neither the name of the copyright holder nor the names of its
  19  * contributors may be used to endorse or promote products derived from
  20  * this software without specific prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  24  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  26  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  27  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  28  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  29  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  30  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  31  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  32  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef UNBOUND_DNSTAP_H
  36 #define UNBOUND_DNSTAP_H
  37
  38 #include "dnstap/dnstap_config.h"
  39
  40 #ifdef USE_DNSTAP
  41
  42 struct config_file;
  43 struct fstrm_io;
  44 struct fstrm_queue;
  45 struct sldns_buffer;
  46
  47 struct dt_env {
  48         /** dnstap I/O thread */
  49         struct fstrm_iothr *iothr;
  50
  51         /** dnstap I/O thread input queue */
  52         struct fstrm_iothr_queue *ioq;
  53
  54         /** dnstap "identity" field, NULL if disabled */
  55         char *identity;
  56
  57         /** dnstap "version" field, NULL if disabled */
  58         char *version;
  59
  60         /** length of "identity" field */
  61         unsigned len_identity;
  62
  63         /** length of "version" field */
  64         unsigned len_version;
  65
  66         /** whether to log Message/RESOLVER_QUERY */
  67         unsigned log_resolver_query_messages : 1;
  68         /** whether to log Message/RESOLVER_RESPONSE */
  69         unsigned log_resolver_response_messages : 1;
  70         /** whether to log Message/CLIENT_QUERY */
  71         unsigned log_client_query_messages : 1;
  72         /** whether to log Message/CLIENT_RESPONSE */
  73         unsigned log_client_response_messages : 1;
  74         /** whether to log Message/FORWARDER_QUERY */
  75         unsigned log_forwarder_query_messages : 1;
  76         /** whether to log Message/FORWARDER_RESPONSE */
  77         unsigned log_forwarder_response_messages : 1;
  78 };
  79
  80 /**
  81  * Create dnstap environment object. Afterwards, call dt_apply_cfg() to fill in
  82  * the config variables and dt_init() to fill in the per-worker state. Each
  83  * worker needs a copy of this object but with its own I/O queue (the fq field
  84  * of the structure) to ensure lock-free access to its own per-worker circular
  85  * queue.  Duplicate the environment object if more than one worker needs to
  86  * share access to the dnstap I/O socket.
  87  * @param socket_path: path to dnstap logging socket, must be non-NULL.
  88  * @param num_workers: number of worker threads, must be > 0.
  89  * @return dt_env object, NULL on failure.
  90  */
  91 struct dt_env *
  92 dt_create(const char *socket_path, unsigned num_workers);
  93
  94 /**
  95  * Apply config settings.
  96  * @param env: dnstap environment object.
  97  * @param cfg: new config settings.
  98  */
  99 void
 100 dt_apply_cfg(struct dt_env *env, struct config_file *cfg);
 101
 102 /**
 103  * Initialize per-worker state in dnstap environment object.
 104  * @param env: dnstap environment object to initialize, created with dt_create().
 105  * @return: true on success, false on failure.
 106  */
 107 int
 108 dt_init(struct dt_env *env);
 109
 110 /**
 111  * Delete dnstap environment object. Closes dnstap I/O socket and deletes all
 112  * per-worker I/O queues.
 113  */
 114 void
 115 dt_delete(struct dt_env *env);
 116
 117 /**
 118  * Create and send a new dnstap "Message" event of type CLIENT_QUERY.
 119  * @param env: dnstap environment object.
 120  * @param qsock: address/port of client.
 121  * @param cptype: comm_udp or comm_tcp.
 122  * @param qmsg: query message.
 123  */
 124 void
 125 dt_msg_send_client_query(struct dt_env *env,
 126                          struct sockaddr_storage *qsock,
 127                          enum comm_point_type cptype,
 128                          struct sldns_buffer *qmsg);
 129
 130 /**
 131  * Create and send a new dnstap "Message" event of type CLIENT_RESPONSE.
 132  * @param env: dnstap environment object.
 133  * @param qsock: address/port of client.
 134  * @param cptype: comm_udp or comm_tcp.
 135  * @param rmsg: response message.
 136  */
 137 void
 138 dt_msg_send_client_response(struct dt_env *env,
 139                             struct sockaddr_storage *qsock,
 140                             enum comm_point_type cptype,
 141                             struct sldns_buffer *rmsg);
 142
 143 /**
 144  * Create and send a new dnstap "Message" event of type RESOLVER_QUERY or
 145  * FORWARDER_QUERY. The type used is dependent on the value of the RD bit
 146  * in the query header.
 147  * @param env: dnstap environment object.
 148  * @param rsock: address/port of server the query is being sent to.
 149  * @param cptype: comm_udp or comm_tcp.
 150  * @param zone: query zone.
 151  * @param zone_len: length of zone.
 152  * @param qmsg: query message.
 153  */
 154 void
 155 dt_msg_send_outside_query(struct dt_env *env,
 156                           struct sockaddr_storage *rsock,
 157                           enum comm_point_type cptype,
 158                           uint8_t *zone, size_t zone_len,
 159                           struct sldns_buffer *qmsg);
 160
 161 /**
 162  * Create and send a new dnstap "Message" event of type RESOLVER_RESPONSE or
 163  * FORWARDER_RESPONSE. The type used is dependent on the value of the RD bit
 164  * in the query header.
 165  * @param env: dnstap environment object.
 166  * @param rsock: address/port of server the response was received from.
 167  * @param cptype: comm_udp or comm_tcp.
 168  * @param zone: query zone.
 169  * @param zone_len: length of zone.
 170  * @param qbuf: outside_network's qbuf key.
 171  * @param qbuf_len: length of outside_network's qbuf key.
 172  * @param qtime: time query message was sent.
 173  * @param rtime: time response message was sent.
 174  * @param rmsg: response message.
 175  */
 176 void
 177 dt_msg_send_outside_response(struct dt_env *env,
 178                              struct sockaddr_storage *rsock,
 179                              enum comm_point_type cptype,
 180                              uint8_t *zone, size_t zone_len,
 181                              uint8_t *qbuf, size_t qbuf_len,
 182                              const struct timeval *qtime,
 183                              const struct timeval *rtime,
 184                              struct sldns_buffer *rmsg);
 185
 186 #endif /* USE_DNSTAP */
 187
 188 #endif /* UNBOUND_DNSTAP_H */