[apple/network_cmds.git] / unbound / dnstap / dnstap.h

/* dnstap support for Unbound */

/*
 * Copyright (c) 2013-2014, Farsight Security, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef UNBOUND_DNSTAP_H
#define UNBOUND_DNSTAP_H

#include "dnstap/dnstap_config.h"

#ifdef USE_DNSTAP

struct config_file;
struct fstrm_io;
struct fstrm_queue;
struct sldns_buffer;

struct dt_env {
	/** dnstap I/O thread */
	struct fstrm_iothr *iothr;

	/** dnstap I/O thread input queue */
	struct fstrm_iothr_queue *ioq;

	/** dnstap "identity" field, NULL if disabled */
	char *identity;

	/** dnstap "version" field, NULL if disabled */
	char *version;

	/** length of "identity" field */
	unsigned len_identity;

	/** length of "version" field */
	unsigned len_version;

	/** whether to log Message/RESOLVER_QUERY */
	unsigned log_resolver_query_messages : 1;
	/** whether to log Message/RESOLVER_RESPONSE */
	unsigned log_resolver_response_messages : 1;
	/** whether to log Message/CLIENT_QUERY */
	unsigned log_client_query_messages : 1;
	/** whether to log Message/CLIENT_RESPONSE */
	unsigned log_client_response_messages : 1;
	/** whether to log Message/FORWARDER_QUERY */
	unsigned log_forwarder_query_messages : 1;
	/** whether to log Message/FORWARDER_RESPONSE */
	unsigned log_forwarder_response_messages : 1;
};

/**
 * Create dnstap environment object. Afterwards, call dt_apply_cfg() to fill in
 * the config variables and dt_init() to fill in the per-worker state. Each
 * worker needs a copy of this object but with its own I/O queue (the fq field
 * of the structure) to ensure lock-free access to its own per-worker circular
 * queue.  Duplicate the environment object if more than one worker needs to
 * share access to the dnstap I/O socket.
 * @param socket_path: path to dnstap logging socket, must be non-NULL.
 * @param num_workers: number of worker threads, must be > 0.
 * @return dt_env object, NULL on failure.
 */
struct dt_env *
dt_create(const char *socket_path, unsigned num_workers);

/**
 * Apply config settings.
 * @param env: dnstap environment object.
 * @param cfg: new config settings.
 */
void
dt_apply_cfg(struct dt_env *env, struct config_file *cfg);

/**
 * Initialize per-worker state in dnstap environment object.
 * @param env: dnstap environment object to initialize, created with dt_create().
 * @return: true on success, false on failure.
 */
int
dt_init(struct dt_env *env);

/**
 * Delete dnstap environment object. Closes dnstap I/O socket and deletes all
 * per-worker I/O queues.
 */
void
dt_delete(struct dt_env *env);

/**
 * Create and send a new dnstap "Message" event of type CLIENT_QUERY.
 * @param env: dnstap environment object.
 * @param qsock: address/port of client.
 * @param cptype: comm_udp or comm_tcp.
 * @param qmsg: query message.
 */
void
dt_msg_send_client_query(struct dt_env *env,
			 struct sockaddr_storage *qsock,
			 enum comm_point_type cptype,
			 struct sldns_buffer *qmsg);

/**
 * Create and send a new dnstap "Message" event of type CLIENT_RESPONSE.
 * @param env: dnstap environment object.
 * @param qsock: address/port of client.
 * @param cptype: comm_udp or comm_tcp.
 * @param rmsg: response message.
 */
void
dt_msg_send_client_response(struct dt_env *env,
			    struct sockaddr_storage *qsock,
			    enum comm_point_type cptype,
			    struct sldns_buffer *rmsg);

/**
 * Create and send a new dnstap "Message" event of type RESOLVER_QUERY or
 * FORWARDER_QUERY. The type used is dependent on the value of the RD bit
 * in the query header.
 * @param env: dnstap environment object.
 * @param rsock: address/port of server the query is being sent to.
 * @param cptype: comm_udp or comm_tcp.
 * @param zone: query zone.
 * @param zone_len: length of zone.
 * @param qmsg: query message.
 */
void
dt_msg_send_outside_query(struct dt_env *env,
			  struct sockaddr_storage *rsock,
			  enum comm_point_type cptype,
			  uint8_t *zone, size_t zone_len,
			  struct sldns_buffer *qmsg);

/**
 * Create and send a new dnstap "Message" event of type RESOLVER_RESPONSE or
 * FORWARDER_RESPONSE. The type used is dependent on the value of the RD bit
 * in the query header.
 * @param env: dnstap environment object.
 * @param rsock: address/port of server the response was received from.
 * @param cptype: comm_udp or comm_tcp.
 * @param zone: query zone.
 * @param zone_len: length of zone.
 * @param qbuf: outside_network's qbuf key.
 * @param qbuf_len: length of outside_network's qbuf key.
 * @param qtime: time query message was sent.
 * @param rtime: time response message was sent.
 * @param rmsg: response message.
 */
void
dt_msg_send_outside_response(struct dt_env *env,
			     struct sockaddr_storage *rsock,
			     enum comm_point_type cptype,
			     uint8_t *zone, size_t zone_len,
			     uint8_t *qbuf, size_t qbuf_len,
			     const struct timeval *qtime,
			     const struct timeval *rtime,
			     struct sldns_buffer *rmsg);

#endif /* USE_DNSTAP */

#endif /* UNBOUND_DNSTAP_H */
Commit	Line	Data
89c4ed63 A	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 */