Adds more Doxygen documentation in preparation for 2.6.9

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = Fwknop
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.6.8
+PROJECT_NUMBER         = 2.6.9
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

server/access.c

@@ -53,6 +53,17 @@
   DECLARE_TEST_SUITE(access, "Access test suite");
 #endif
 
+/**
+ * \brief include keys file
+ *
+ * This function loads only the crypto keys from a given file.
+ * It inserts these keys into the active access stanza.
+ *
+ * \param curr_acc pointer to the current access stanza
+ * \param access_filename Pointer to the file containing the keys
+ * \param opts fko_srv_options_t Server options struct
+ *
+ */
 int
 include_keys_file(acc_stanza_t *, const char *, fko_srv_options_t *);
 
@@ -1051,6 +1062,15 @@ free_acc_stanzas(fko_srv_options_t *opts)
     return;
 }
 
+/**
+ * \brief Frees the final access stanza
+ *
+ * This function walks the access stanza list and frees the last member
+ *
+ * \param opts pointer to the server options struct
+ *
+ */
+
 void
 free_last_acc_stanza(fko_srv_options_t *opts)
 {
@@ -1404,11 +1424,7 @@ acc_data_is_valid(fko_srv_options_t *opts,
 
     return(1);
 }
-/**
- * \brief Parses an access folder
- *
- * This function processes all the *.conf files in the specified directory.
- */
+
 int
 parse_access_folder(fko_srv_options_t *opts, char *access_folder, int *depth)
 {
@@ -2049,11 +2065,20 @@ compare_addr_list(acc_int_list_t *ip_list, const uint32_t ip)
     return(match);
 }
 
-/* Compare the contents of 2 port lists.  Return true on a match.
+/**
+ * \brief Compares port lists
+ *
+ * Compare the contents of 2 port lists.  Return true on a match.
  * Match depends on the match_any flag.  if match_any is 1 then any
  * entry in the incoming data need only match one item to return true.
  * Otherwise all entries in the incoming data must have a corresponding
  * match in the access port_list.
+ *
+ * \param acc Pointer to the acc_stanza_t struct that holds the access stanzas
+ * \param port_str pointer to the
+ *
+ * \return Returns true on a match
+ *
  */
 static int
 compare_port_list(acc_port_list_t *in, acc_port_list_t *ac, const int match_any)

server/access.h

@@ -33,26 +33,145 @@
 #define PROTO_TCP   6
 #define PROTO_UDP   17
 
-/* Allow strings as large as 123.123.123.123/255.255.255.255
+/**
+ * \def ACCESS_BUF_LEN
+ *
+ * \brief Allow strings as large as 123.123.123.123/255.255.255.255
  */
 #define ACCESS_BUF_LEN  33
 
-/* We won't recurse more than 3 deep.  Access.conf can include a file
+/**
+ * \def MAX_DEPTH
+ *
+ * \brief Recursion depth
+ *
+ * We won't recurse more than 3 deep.  Access.conf can include a file
  * that includes a file, but that's the limit.
 */
 #define MAX_DEPTH 3
 
 /* Function Prototypes
 */
+
+/**
+ * \brief Loads an access.conf file
+ *
+ * Also handles includes by calling itself recursively, only recurses 3 levels deep
+ *
+ * \param opts Pointer to the fko_srv_options_t struct to populate
+ * \param access_filename Pointer to the filename to load
+ * \param depth Pointer to the current depth.  This starts at 0 and is incremented for each recursion
+ *
+ * \return Returns an error status, or EXIT_SUCCESS
+ *
+ */
 int parse_access_file(fko_srv_options_t *opts, char *access_filename, int *depth);
+
+/**
+ * \brief Loads access.conf files in a folder
+ *
+ * This function does not recurse into subfolders, but calls parse_access_file
+ * for each contained file.  This function does not increment the depth int.
+ *
+ * \param opts Pointer to the fko_srv_options_t struct to populate
+ * \param access_folder Pointer to the folder name to process
+ * \param depth Pointer to the current depth.
+ *
+ * \return Returns an error status, or EXIT_SUCCESS
+ *
+ */
 int parse_access_folder(fko_srv_options_t *opts, char *access_folder, int *depth);
+
+/**
+ * \brief Basic validation for a access stanzas
+ *
+ * This is a basic check to ensure there is at least one access stanza
+ * with the "source" variable populated, and this function is only
+ * called after all access.conf files are processed. This allows
+ * %include_folder processing to proceed against directories that
+ * have files that are not access.conf files. Additional stronger
+ * validations are done in acc_data_is_valid(), but this function
+ * is only called when a "SOURCE" variable has been parsed out of
+ * the file.
+ *
+ * \param acc Pointer to the acc_stanza_t struct that holds the access stanza
+ *
+ * \return Returns an error status, or EXIT_SUCCESS
+ *
+ */
 int valid_access_stanzas(acc_stanza_t *acc);
+
+/**
+ * \brief Compares address lists
+ *
+ * This function walks a linked list looking for a matching IP address.
+ * Primarily intended to find a matching access stanza for an
+ * incoming SPA packet.
+ *
+ * \param source_list pointer to linked list to walk
+ * \param ip Address to compare
+ *
+ * \return Returns true on a match
+ *
+ */
 int compare_addr_list(acc_int_list_t *source_list, const uint32_t ip);
+
+/**
+ * \brief Check for a proto-port string
+ *
+ * Take a proto/port string (or mulitple comma-separated strings) and check
+ * them against the list for the given access stanza.
+ *
+ * \param acc Pointer to the acc_stanza_t struct that holds the access stanzas
+ * \param port_str pointer to the port string to look for
+ *
+ * \return Returns true if allowed
+ *
+ */
 int acc_check_port_access(acc_stanza_t *acc, char *port_str);
+
+/**
+ * \brief Dumps the current configuration to stdout
+ *
+ * \param opts pointer to the server options struct
+ *
+ */
 void dump_access_list(const fko_srv_options_t *opts);
+
+/**
+ * \brief Expands a proto/port string to a list of access proto-port struct.
+ *
+ * This takes a single string of comma separated proto/port values and separates
+ * them into a linked list
+ *
+ * \param plist Double pointer to the acc_port_list_t to hold the proto/ports
+ * \param plist_str Pointer to the list of proto/port values
+ *
+ * \return Returns true if successful
+ *
+ */
 int expand_acc_port_list(acc_port_list_t **plist, char *plist_str);
+
+/**
+ * \brief Sets do_acc_stanza_init to true, which enables free_acc_stanzas()
+ *
+ */
 void enable_acc_stanzas_init(void);
+
+/**
+ * \brief Free memory for all access stanzas
+ *
+ * \param opts Pointer to fko_srv_options_t that contains the access stanza chain to free
+ *
+ */
 void free_acc_stanzas(fko_srv_options_t *opts);
+
+/**
+ * \brief free a port list
+ *
+ * \param plist Pointer to acc_port_list_t to free
+ *
+ */
 void free_acc_port_list(acc_port_list_t *plist);
 
 #ifdef HAVE_C_UNIT_TESTS

server/cmd_cycle.h

@@ -33,9 +33,40 @@
 
 #define CMD_CYCLE_BUFSIZE 256
 
+/**
+ * \brief Main driver for open/close command cycles
+ *
+ * This function is called when a valid SPA packet is received that matches
+ * a stanza containing a command cycle.
+ *
+ * \param opts
+ * \param acc
+ * \param spadat
+ * \param stanza_num
+ * \param res
+ *
+ */
 int cmd_cycle_open(fko_srv_options_t *opts, acc_stanza_t *acc,
         spa_data_t *spadat, const int stanza_num, int *res);
+
+/**
+ * \brief Launches the command cycle close command
+ *
+ * TODO: finish me
+ *
+ * \param opts
+ *
+ */
 void cmd_cycle_close(fko_srv_options_t *opts);
+
+/**
+ * \brief frees the command cycle list
+ *
+ * TODO: Finish me
+ *
+ * \param opts
+ *
+ */
 void free_cmd_cycle_list(fko_srv_options_t *opts);
 
 #endif  /* CMD_CYCLE_H */

server/cmd_opts.h

@@ -150,7 +150,7 @@ static char *config_map[NUMBER_OF_CONFIG_ENTRIES] = {
 };
 
 
-/* Long options values (for those that may not have a short option).
+/** Long options values (for those that may not have a short option).
 */
 enum {
     FW_LIST         = 0x200,

server/config_init.h

@@ -35,10 +35,39 @@
 
 /* Function Prototypes
 */
+
+/**
+ * \brief Initializes the program config
+ *
+ * This function sets default config options and loads the config information from the command line.
+ *
+ * \param opts fko_srv_options_t struct that is populated with configuration
+ * \param argc argument count, the number of command line arguments
+ * \param argv argument vector, an array of the command line arguments
+ *
+ */
 void config_init(fko_srv_options_t *opts, int argc, char **argv);
+
+/**
+ * \brief dumps current config to std out
+ *
+ * \param opts Pointer to the program options struct to dump
+ *
+ */
 void dump_config(const fko_srv_options_t *opts);
-void clear_configs(fko_srv_options_t *opts);
+
+/**
+ * \brief Frees config memory
+ *
+ * \param opts fko_srv_options_t struct that is to be freed
+ *
+ */
 void free_configs(fko_srv_options_t *opts);
+
+/**
+ * \brief Prints program help message to stdout
+ *
+ */
 void usage(void);
 
 #endif /* CONFIG_INIT_H */

server/extcmd.h

@@ -82,18 +82,108 @@ enum {
 
 /* Function prototypes
 */
+
+
+
+/**
+ * \brief Runs an external command
+ *
+ * This function is actually a wrapper for _run_extcmd().
+ * Run an external command returning exit status, and optionally filling
+ * provided buffer with STDOUT output up to the size provided.
+ *
+ * \param cmd Command to run
+ * \param so_buf Buffer for command output, or null pointer to discard output
+ * \param so_buf_sz length of so_buf
+ * \param want_stderr Flag indicating stderr is to be saved
+ * \param timeout Placeholder, the timeout is not used
+ * \param pid_status Pointer where the command status is stored
+ * \param opts Program options struct
+ *
+ */
 int run_extcmd(const char *cmd, char *so_buf, const size_t so_buf_sz,
         const int want_stderr, const int timeout, int *pid_status,
         const fko_srv_options_t * const opts);
+
+/**
+ * \brief Runs an external command as a given user and group
+ *
+ * This function is actually a wrapper for _run_extcmd().
+ * Run an external command returning exit status, and optionally filling
+ * provided buffer with STDOUT output up to the size provided.
+ * This function takes a user ID and Group ID to use when running the command.
+ *
+ * \param uid User to run as
+ * \param gid Group to run as
+ * \param cmd Command to run
+ * \param so_buf Buffer for command output
+ * \param so_buf_sz length of so_buf
+ * \param want_stderr Flag indicating stderr is to be saved
+ * \param timeout Placeholder, the timeout is not used
+ * \param pid_status Pointer where the command status is stored
+ * \param opts Program options struct
+ *
+ */
 int run_extcmd_as(uid_t uid, gid_t gid, const char *cmd, char *so_buf,
         const size_t so_buf_sz, const int want_stderr, const int timeout,
         int *pid_status, const fko_srv_options_t * const opts);
+
+/**
+ * \brief Runs an external command, searching for a substring
+ *
+ * This function is actually a wrapper for _run_extcmd().
+ * Run an external command returning exit status, and optionally filling
+ * provided buffer with STDOUT output up to the size provided.
+ *
+ * \param cmd Command to run
+ * \param want_stderr Flag indicating stderr is to be saved
+ * \param timeout Placeholder, the timeout is not used
+ * \param substr_search The substring to search for
+ * \param pid_status Pointer where the command status is stored
+ * \param opts Program options struct
+ *
+ * \return Returns line number where the substring was matched, or 0 for no match
+ */
 int search_extcmd(const char *cmd, const int want_stderr,
         const int timeout, const char *substr_search,
         int *pid_status, const fko_srv_options_t * const opts);
+
+/**
+ * \brief Runs an external command, returning a line of output
+ *
+ * This function is actually a wrapper for _run_extcmd().
+ * Run an external command returning exit status, and optionally filling
+ * provided buffer with STDOUT output up to the size provided.
+ * This function searches the command output for the first match against
+ * The provided substring, returns the line number that matched,
+ * and populates so_buf with that line of output.
+ *
+ * \param cmd Command to run
+ * \param so_buf Buffer for command output
+ * \param so_buf_sz length of so_buf
+ * \param timeout Placeholder, the timeout is not used
+ * \param substr_search The substring to search for
+ * \param pid_status Pointer where the command status is stored
+ * \param opts Program options struct
+ *
+ * \return Returns the line number that matched, or 0 for no match
+ */
 int search_extcmd_getline(const char *cmd, char *so_buf, const size_t so_buf_sz,
         const int timeout, const char *substr_search, int *pid_status,
         const fko_srv_options_t * const opts);
+
+/**
+ * \brief Runs an external command, and feeds it stdin
+ *
+ * This function is actually a wrapper for _run_extcmd_write().
+ * Run an external command that expects stdin.
+ *
+ * \param cmd Command to run
+ * \param cmd_write The text to send as stdin
+ * \param pid_status Pointer where the command status is stored
+ * \param opts Program options struct
+ *
+ */
 int run_extcmd_write(const char *cmd, const char *cmd_write, int *pid_status,
         const fko_srv_options_t * const opts);
 #endif /* EXTCMD_H */

server/fwknopd.h

@@ -43,18 +43,43 @@
  * of defining them here.
 */
 #ifndef LOCK_SH
-  #define   LOCK_SH        0x01      /* shared file lock */
+  /**
+   * \def LOCK_SH
+   *
+   * \brief Shared file lock
+   */
+  #define   LOCK_SH        0x01
 #endif
 #ifndef LOCK_EX
-  #define   LOCK_EX        0x02      /* exclusive file lock */
+  /**
+   * \def LOCK_EX
+   *
+   * \brief Exclusive file lock
+   */
+  #define   LOCK_EX        0x02
 #endif
 #ifndef LOCK_NB
-  #define   LOCK_NB        0x04      /* do not block when locking */
+  /**
+   * \def LOCK_NB
+   *
+   * \brief Do not block when locking
+   */
+  #define   LOCK_NB        0x04
 #endif
 #ifndef LOCK_UN
-  #define   LOCK_UN        0x08      /* unlock file */
+  /**
+   * \def LOCK_UN
+   *
+   * \brief Unlock file
+   */
+  #define   LOCK_UN        0x08
 #endif
 
+  /**
+   * \def PID_BUFLEN
+   *
+   * \brief Buffer length for PID
+   */
 #define PID_BUFLEN 7
 
 #endif  /* FWKNOPD_H */

server/fwknopd_common.h

@@ -732,6 +732,15 @@ typedef struct fko_srv_options
 */
 #define FW_CLEANUP          1
 #define NO_FW_CLEANUP       0
+
+/**
+ * \brief Frees all memory and exits
+ *
+ * \param opts Program options
+ * \param fw_cleanup_flag Flag indicates whether firewall needs cleanup
+ * \param exit_status Exit status to return when closing the program
+ *
+ */
 void clean_exit(fko_srv_options_t *opts,
         unsigned int fw_cleanup_flag, unsigned int exit_status);
 

server/fwknopd_errors.h

@@ -68,7 +68,19 @@ enum {
 
 /* Function prototypes
 */
+
+/**
+ * \brief takes a numeric error code and returns the readable string
+ *
+ * \param err_code The integer error code to convert
+ *
+ * \return returns a pointer to the error string
+ */
 const char* get_errstr(const int err_code);
+
+/**
+ * \brief print all server errors (from server/fwknopd_errors.c) to stdout
+ */
 void dump_server_errors(void);
 
 #endif /* FWKNOPD_ERRORS_H */

server/incoming_spa.h

@@ -32,6 +32,16 @@
 
 /* Prototypes
 */
+
+/**
+ * \brief Process the SPA packet data
+ *
+ * This is the central function for handling incoming SPA data.  It is called
+ * once for each SPA packet to process
+ *
+ * \param opts Main program data struct
+ *
+ */
 void incoming_spa(fko_srv_options_t *opts);
 
 #endif  /* INCOMING_SPA_H */

server/nfq_capture.c

@@ -1,10 +1,10 @@
+/**
+ * \file server/nfq_capture.c
+ *
+ * \brief Capture routine for fwknopd that uses libnetfilter_queue.
+ */
+
 /*
- *****************************************************************************
- *
- * File:    nfq_capture.c
- *
- * Purpose: Capture routine for fwknopd that uses libnetfilter_queue.
- *
  *  Fwknop is developed primarily by the people listed in the file 'AUTHORS'.
  *  Copyright (C) 2009-2014 fwknop developers and contributors. For a full
  *  list of contributors, see the file 'CREDITS'.

server/nfq_capture.h

@@ -1,10 +1,10 @@
+/**
+ * \file server/nfq_capture.h
+ *
+ * \brief Header file for nfq_capture.c
+ */
+
 /*
- *****************************************************************************
- *
- * File:    nfq_capture.h
- *
- * Purpose: Header file for nfq_capture.c.
- *
  *  Fwknop is developed primarily by the people listed in the file 'AUTHORS'.
  *  Copyright (C) 2009-2014 fwknop developers and contributors. For a full
  *  list of contributors, see the file 'CREDITS'.