summaryrefslogtreecommitdiffstats
path: root/src/fastd.h
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2014-05-25 04:59:35 +0200
committerMatthias Schiffer <mschiffer@universe-factory.net>2014-05-25 04:59:35 +0200
commit5e72359e9a2f4008c408acbd3fe5d389e11a15b4 (patch)
tree5f1aede16a3b1e6985d4b7a309c6999416a638a3 /src/fastd.h
parentf34e51a1c3b98df2b7c8c7d7eb415a33f42f2d75 (diff)
downloadfastd-5e72359e9a2f4008c408acbd3fe5d389e11a15b4.tar
fastd-5e72359e9a2f4008c408acbd3fe5d389e11a15b4.zip
Completely document fastd.h
Diffstat (limited to 'src/fastd.h')
-rw-r--r--src/fastd.h175
1 files changed, 91 insertions, 84 deletions
diff --git a/src/fastd.h b/src/fastd.h
index 67174cf..f9e8c5a 100644
--- a/src/fastd.h
+++ b/src/fastd.h
@@ -166,134 +166,134 @@ struct fastd_config {
fastd_loglevel_t log_syslog_level; /**< The minimum loglevel of messages to print to syslog (or -1 to not print any messages on syslog) */
char *log_syslog_ident; /**< The identification string for messages sent to syslog (default: "fastd") */
- char *ifname;
+ char *ifname; /**< The configured interface name */
- size_t n_bind_addrs;
- fastd_bind_address_t *bind_addrs;
+ size_t n_bind_addrs; /**< Number of elements in bind_addrs */
+ fastd_bind_address_t *bind_addrs; /**< Configured bind addresses */
- fastd_bind_address_t *bind_addr_default_v4;
- fastd_bind_address_t *bind_addr_default_v6;
+ fastd_bind_address_t *bind_addr_default_v4; /**< Pointer to the bind address to be used for IPv4 connections by default */
+ fastd_bind_address_t *bind_addr_default_v6; /**< Pointer to the bind address to be used for IPv6 connections by default */
- uint16_t mtu;
- fastd_mode_t mode;
+ uint16_t mtu; /**< The configured MTU */
+ fastd_mode_t mode; /**< The configured mode of operation */
- uint32_t packet_mark;
- bool forward;
- fastd_tristate_t pmtu;
- bool secure_handshakes;
+ uint32_t packet_mark; /**< The configured packet mark (or 0) */
+ bool forward; /**< Specifies if packet forwarding is enable */
+ fastd_tristate_t pmtu; /**< Can be set to explicitly enable or disable PMTU detection */
+ bool secure_handshakes; /**< Can be set to false to support connections with fastd versions before v11 */
- fastd_drop_caps_t drop_caps;
+ fastd_drop_caps_t drop_caps; /**< Specifies if and when to drop capabilities */
- char *user;
- char *group;
+ char *user; /**< Specifies which user to switch to after initialization */
+ char *group; /**< Can specify an alternative group to switch to */
- uid_t uid;
- gid_t gid;
- size_t n_groups;
- gid_t *groups;
+ uid_t uid; /**< The UID of the configured user */
+ gid_t gid; /**< The GID of the configured group */
+ size_t n_groups; /**< The number of supplementary groups of the user */
+ gid_t *groups; /**< The supplementary groups of the configured user */
- const fastd_protocol_t *protocol;
- fastd_string_stack_t *method_list;
- fastd_method_info_t *methods;
+ const fastd_protocol_t *protocol; /**< The handshake protocol */
+ fastd_string_stack_t *method_list; /**< The list of configured method names */
+ fastd_method_info_t *methods; /**< The list of configured methods */
- size_t max_overhead;
- size_t min_encrypt_head_space;
- size_t min_decrypt_head_space;
- size_t min_encrypt_tail_space;
- size_t min_decrypt_tail_space;
+ size_t max_overhead; /**< The maximum overhead of all configured methods */
+ size_t min_encrypt_head_space; /**< The minimum space a configured methods needs a the beginning of a buffer to encrypt */
+ size_t min_decrypt_head_space; /**< The minimum space a configured methods needs a the beginning of a buffer to decrypt */
+ size_t min_encrypt_tail_space; /**< The minimum space a configured methods needs a the end of a buffer to encrypt */
+ size_t min_decrypt_tail_space; /**< The minimum space a configured methods needs a the end of a buffer to decrypt */
- char *secret;
+ char *secret; /**< The configured secret key */
- const fastd_cipher_t **ciphers;
- const fastd_mac_t **macs;
+ const fastd_cipher_t **ciphers; /**< All supported ciphers */
+ const fastd_mac_t **macs; /**< All supported message authentication codes */
- fastd_peer_group_config_t *peer_group;
- fastd_peer_config_t *peers;
+ fastd_peer_group_config_t *peer_group; /**< The root peer group configuration */
+ fastd_peer_config_t *peers; /**< The configured peers */
- bool has_floating;
+ bool has_floating; /**< Specifies if any of the configured peers have floating remotes */
- fastd_protocol_config_t *protocol_config;
+ fastd_protocol_config_t *protocol_config; /**< The protocol-specific configuration */
- fastd_shell_command_t on_pre_up;
- fastd_shell_command_t on_up;
- fastd_shell_command_t on_down;
- fastd_shell_command_t on_post_down;
- fastd_shell_command_t on_connect;
- fastd_shell_command_t on_establish;
- fastd_shell_command_t on_disestablish;
+ fastd_shell_command_t on_pre_up; /**< The command to execute before the initialization of the tunnel interface */
+ fastd_shell_command_t on_up; /**< The command to execute after the initialization of the tunnel interface */
+ fastd_shell_command_t on_down; /**< The command to execute before the destruction of the tunnel interface */
+ fastd_shell_command_t on_post_down; /**< The command to execute after the destruction of the tunnel interface */
+ fastd_shell_command_t on_connect; /**< The command to execute before a handshake is sent to establish a new connection */
+ fastd_shell_command_t on_establish; /**< The command to execute when a new connection has been established */
+ fastd_shell_command_t on_disestablish; /**< The command to execute when a connection has been disestablished */
#ifdef WITH_VERIFY
- fastd_shell_command_t on_verify;
+ fastd_shell_command_t on_verify; /**< The command to execute to check if a connection from an unknown peer should be allowed */
#endif
- bool daemon;
- char *pid_file;
+ bool daemon; /**< Set to make fastd fork to the background after initialization */
+ char *pid_file; /**< A filename to write fastd's PID to */
- bool hide_ip_addresses;
- bool hide_mac_addresses;
+ bool hide_ip_addresses; /**< Tells fastd to hide peers' IP address in the log output */
+ bool hide_mac_addresses; /**< Tells fastd to hide peers' MAC address in the log output */
- bool machine_readable;
- bool generate_key;
- bool show_key;
- bool verify_config;
+ bool machine_readable; /**< Supresses explanatory messages in the generate_key and show_key commands */
+ bool generate_key; /**< Makes fastd generate a new keypair and exit */
+ bool show_key; /**< Makes fastd output the public key for the configured secret and exit */
+ bool verify_config; /**< Does basic verification of the configuration and exits */
};
/** The dynamic state of \em fastd */
struct fastd_context {
- bool log_initialized;
+ bool log_initialized; /**< true if the logging facilities have been properly initialized */
- char *ifname;
+ char *ifname; /**< The actual interface name */
- struct timespec now;
+ struct timespec now; /**< The current monotonous timestamp */
- fastd_peer_group_t *peer_group;
+ fastd_peer_group_t *peer_group; /**< The root peer group */
- uint64_t next_peer_id;
- VECTOR(fastd_peer_t*) peers;
+ uint64_t next_peer_id; /**< An monotonously increasing ID peers are identified with in some components */
+ VECTOR(fastd_peer_t*) peers; /**< The currectly active peers */
#ifdef USE_EPOLL
- int epoll_fd;
+ int epoll_fd; /**< The file descriptor for the epoll facility */
#else
- VECTOR(struct pollfd) pollfds;
+ VECTOR(struct pollfd) pollfds; /**< The vector of pollfds for all file descriptors */
#endif
- uint32_t peer_addr_ht_seed;
- VECTOR(fastd_peer_t*) *peer_addr_ht;
+ uint32_t peer_addr_ht_seed; /**< The hash seed used for peer_addr_ht */
+ VECTOR(fastd_peer_t*) *peer_addr_ht; /**< An array of hash buckets for the peer hash table */
- fastd_dlist_head_t handshake_queue;
- struct timespec next_maintenance;
+ fastd_dlist_head_t handshake_queue; /**< A doubly linked list of the peers currently queued for handshakes (ordered by the time of the next handshake) */
+ struct timespec next_maintenance; /**< The time of the next maintenance call */
- VECTOR(pid_t) async_pids;
- int async_rfd;
- int async_wfd;
+ VECTOR(pid_t) async_pids; /**< PIDs of asynchronously executed commands which still have to be reaped */
+ int async_rfd; /**< The read side of the pipe used to send data from other thread to the main thread */
+ int async_wfd; /**< The write side of the pipe used to send data from other thread to the main thread */
- int tunfd;
+ int tunfd; /**< The file descriptor of the tunnel interface */
- size_t n_socks;
- fastd_socket_t *socks;
+ size_t n_socks; /**< The number of sockets in socks */
+ fastd_socket_t *socks; /**< Array of all sockets */
- fastd_socket_t *sock_default_v4;
- fastd_socket_t *sock_default_v6;
+ fastd_socket_t *sock_default_v4; /**< Points to the socket that is used for new outgoing IPv4 connections */
+ fastd_socket_t *sock_default_v6; /**< Points to the socket that is used for new outgoing IPv6 connections */
- fastd_stats_t rx;
+ fastd_stats_t rx; /**< Reception statistics */
- fastd_stats_t tx;
- fastd_stats_t tx_dropped;
- fastd_stats_t tx_error;
+ fastd_stats_t tx; /**< Transmission statistics (OK) */
+ fastd_stats_t tx_dropped; /**< Transmission statistics (dropped because of full queues) */
+ fastd_stats_t tx_error; /**< Transmission statistics (other errors) */
- VECTOR(fastd_peer_eth_addr_t) eth_addrs;
+ VECTOR(fastd_peer_eth_addr_t) eth_addrs; /**< Sorted vector of all known ethernet addresses with associated peers and timeouts */
- unsigned int randseed;
+ unsigned int randseed; /**< Random seed for non-cryptographic random numbers */
- size_t unknown_handshake_pos;
- fastd_handshake_timeout_t unknown_handshakes[8];
+ size_t unknown_handshake_pos; /**< Current start position in the ring buffer unknown_handshakes */
+ fastd_handshake_timeout_t unknown_handshakes[8]; /**< Ring buffer of unknown addresses handshakes have been received from */
- fastd_protocol_state_t *protocol_state;
+ fastd_protocol_state_t *protocol_state; /**< Protocol-specific state */
};
/** A stack of strings */
struct fastd_string_stack {
- fastd_string_stack_t *next;
- char str[];
+ fastd_string_stack_t *next; /**< The next element of the stack */
+ char str[]; /**< Zero-terminated character data */
};
@@ -302,10 +302,10 @@ extern fastd_config_t conf; /**< The global configuration */
void fastd_send(const fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer, size_t stat_size);
-void fastd_send_all(fastd_peer_t *source_peer, fastd_buffer_t buffer);
void fastd_send_handshake(const fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer);
-void fastd_receive(fastd_socket_t *sock);
+void fastd_send_all(fastd_peer_t *source_peer, fastd_buffer_t buffer);
+void fastd_receive(fastd_socket_t *sock);
void fastd_handle_receive(fastd_peer_t *peer, fastd_buffer_t buffer);
void fastd_close_all_fds(void);
@@ -476,7 +476,11 @@ static inline int timespec_diff(const struct timespec *tp1, const struct timespe
}
/**
- Returns true if the given timespec is before or equal to the current time
+ Checks if a timeout has occured
+
+ @param timeout the time the timeout should occur
+
+ @return true if the given timeout is before or equal to the current time
\note The current time is updated only once per main loop iteration, after waiting for input.
*/
@@ -508,7 +512,10 @@ static inline bool fastd_allow_verify(void) {
/**
Checks if two strings are equal
- The strings may be NULL.
+ @param str1 The first string (may be NULL)
+ @param str2 The second string (may be NULL)
+
+ @return True if both strings are NULL or both strings are not NULL and equal
*/
static inline bool strequal(const char *str1, const char *str2) {
if (str1 && str2)