net_cli.h File Reference

#include <stdio.h>
#include <stdarg.h>
#include <sys/time.h>
#include "ev_mgr.h"

Go to the source code of this file.

Data Structures
struct	cli_def
struct	cli_filter
struct	cli_command

Macros
#define	LIBCLI_VERSION_MAJOR   1
#define	LIBCLI_VERISON_MINOR   9
#define	LIBCLI_VERISON_REVISION   7
#define	LIBCLI_VERSION   ((LIBCLI_VERSION_MAJOR << 16) | (LIBCLI_VERSION_MINOR << 8) | LIBCLI_VERSION_REVISION)
#define	CLI_OK   0
#define	CLI_ERROR   -1
#define	CLI_QUIT   -2
#define	CLI_ERROR_ARG   -3
#define	MAX_HISTORY   256
#define	PRIVILEGE_UNPRIVILEGED   0
#define	PRIVILEGE_PRIVILEGED   15
#define	MODE_ANY   -1
#define	MODE_EXEC   0
#define	MODE_CONFIG   1
#define	LIBCLI_HAS_ENABLE   1
#define	PRINT_PLAIN   0
#define	PRINT_FILTERED   0x01
#define	PRINT_BUFFERED   0x02
#define	CLI_MAX_LINE_LENGTH   4096
#define	CLI_MAX_LINE_WORDS   128

Functions
struct cli_def *	cli_init (ksnetEvMgrClass *ke)
	CLI Initialize. More...
int	cli_done (struct cli_def *cli)
	This is optional, but it's a good idea to call this when you are finished with libcli. More...
struct cli_command *	cli_register_command (struct cli_def *cli, struct cli_command *parent, const char *command, int(*callback)(struct cli_def *, const char *, char **, int), int privilege, int mode, const char *help)
int	cli_unregister_command (struct cli_def *cli, const char *command)
	Remove a command command and all children. More...
int	cli_run_command (struct cli_def *cli, const char *command)
int	cli_loop (struct cli_def *cli, int sockfd)
	The main loop of the command-line environment. More...
int	cli_file (struct cli_def *cli, FILE *fh, int privilege, int mode)
	This reads and processes every line read from f as if it were entered at the console. More...
void	cli_set_auth_callback (struct cli_def *cli, int(*auth_callback)(const char *, const char *))
	Enables or disables callback based authentication. More...
void	cli_set_enable_callback (struct cli_def *cli, int(*enable_callback)(const char *))
	Just like cli_set_auth_callback, this takes a pointer to a callback function to authorize privileged access. More...
void	cli_allow_user (struct cli_def *cli, const char *username, const char *password)
	Enables internal authentication, and adds username/password to the list of allowed users. More...
void	cli_allow_enable (struct cli_def *cli, const char *password)
	This will allow a static password to be used for the enable command. More...
void	cli_deny_user (struct cli_def *cli, const char *username)
	Removes username/password from the list of allowed users. More...
void	cli_set_banner (struct cli_def *cli, const char *banner)
	Sets the greeting that clients will be presented with when they connect. More...
void	cli_set_hostname (struct cli_def *cli, const char *hostname)
	Sets the hostname to be displayed as the first part of the prompt. More...
void	cli_set_promptchar (struct cli_def *cli, const char *promptchar)
void	cli_set_modestring (struct cli_def *cli, const char *modestring)
int	cli_set_privilege (struct cli_def *cli, int privilege)
int	cli_set_configmode (struct cli_def *cli, int mode, const char *config_desc)
	This will set the configuration mode. More...
void	cli_reprompt (struct cli_def *cli)
void	cli_regular (struct cli_def *cli, int(*callback)(struct cli_def *cli))
	Adds a callback function which will be called every second that a user is connected to the cli. More...
void	cli_regular_interval (struct cli_def *cli, int seconds)
void	cli_print (struct cli_def *cli, const char *format,...) __attribute__((format(printf
void void	cli_bufprint (struct cli_def *cli, const char *format,...) __attribute__((format(printf
void void void	cli_vabufprint (struct cli_def *cli, const char *format, va_list ap)
void	cli_error (struct cli_def *cli, const char *format,...) __attribute__((format(printf
void void	cli_print_callback (struct cli_def *cli, void(*callback)(struct cli_def *, const char *))
	Whenever cli_print() or cli_error() is called, the output generally goes to the user. More...
void	cli_free_history (struct cli_def *cli)
	Clear history array. More...
void	cli_set_idle_timeout (struct cli_def *cli, unsigned int seconds)
void	cli_set_idle_timeout_callback (struct cli_def *cli, unsigned int seconds, int(*callback)(struct cli_def *))
void	cli_telnet_protocol (struct cli_def *cli, int telnet_protocol)
void	cli_set_context (struct cli_def *cli, void *context)
void *	cli_get_context (struct cli_def *cli)

Macro Definition Documentation

#define CLI_ERROR   -1

Referenced by cli_count_filter(), cli_count_filter_init(), cli_loop(), cli_match_filter(), cli_match_filter_init(), cli_range_filter(), cli_range_filter_init(), and cli_run_command().

#define CLI_ERROR_ARG   -3

#define CLI_MAX_LINE_LENGTH   4096

Referenced by cli_file(), cli_loop(), cli_loop_read(), and cli_loop_set_show_prompt().

#define CLI_MAX_LINE_WORDS   128

Referenced by cli_loop_read(), and cli_run_command().

#define CLI_OK   0

Examples:

teoterm.c.

Referenced by cli_count_filter(), cli_count_filter_init(), cli_done(), cli_file(), cli_int_configure_terminal(), cli_int_disable(), cli_int_enable(), cli_int_exit(), cli_int_help(), cli_int_history(), cli_loop(), cli_loop_check_state(), cli_loop_idle(), cli_match_filter(), cli_match_filter_init(), cli_range_filter(), cli_range_filter_init(), cli_run_command(), cli_show_help(), cli_unregister_command(), and cmd_user().

#define CLI_QUIT   -2

Referenced by cli_file(), cli_int_idle_timeout(), cli_int_quit(), cli_loop_check_state(), cli_loop_read(), and cli_run_command().

#define LIBCLI_HAS_ENABLE   1

#define LIBCLI_VERISON_MINOR   9

#define LIBCLI_VERISON_REVISION   7

#define LIBCLI_VERSION   ((LIBCLI_VERSION_MAJOR << 16) | (LIBCLI_VERSION_MINOR << 8) | LIBCLI_VERSION_REVISION)

#define LIBCLI_VERSION_MAJOR   1

#define MAX_HISTORY   256

Referenced by cli_free_history(), cli_int_history(), and cli_loop_read().

#define MODE_ANY   -1

Referenced by cli_init(), and cli_show_help().

#define MODE_CONFIG   1

Referenced by cli_int_configure_terminal(), and cli_int_exit().

#define MODE_EXEC   0

Examples:

teoterm.c.

Referenced by cli_init(), cli_int_disable(), cli_int_enable(), cli_int_exit(), cli_int_quit(), cli_loop(), cli_loop_read(), and event_cb().

#define PRINT_BUFFERED   0x02

#define PRINT_FILTERED   0x01

Referenced by cli_bufprint(), and cli_print().

#define PRINT_PLAIN   0

Referenced by cli_error().

#define PRIVILEGE_PRIVILEGED   15

Referenced by cli_init(), cli_int_enable(), cli_loop_check_state(), and cli_set_privilege().

#define PRIVILEGE_UNPRIVILEGED   0

Examples:

teoterm.c.

Referenced by cli_init(), cli_int_disable(), cli_int_quit(), cli_loop(), and event_cb().

Function Documentation

void cli_allow_enable	(	struct cli_def *	cli,
		const char *	password
	)

This will allow a static password to be used for the enable command.

This static password will be checked before running any enable callbacks.

Set this to NULL to not have a static enable password.

Parameters

cli
password

References cli_def::enable_password, and free_z.

void cli_allow_user	(	struct cli_def *	cli,
		const char *	username,
		const char *	password
	)

Enables internal authentication, and adds username/password to the list of allowed users.

The internal list of users will be checked before callback based authentication is tried.

Parameters

cli
username
password

References free(), malloc(), and cli_def::users.

void void cli_bufprint	(	struct cli_def *	cli,
		const char *	format,
			...
	)

void cli_deny_user	(	struct cli_def *	cli,
		const char *	username
	)

Removes username/password from the list of allowed users.

If this is the last combination in the list, then internal authentication will be disabled.

Parameters

cli
username

References free(), and cli_def::users.

int cli_done

(

struct cli_def *

cli

)

This is optional, but it's a good idea to call this when you are finished with libcli.

This frees memory used by libcli.

Parameters

cli

Returns

References cli_def::banner, cli_def::buffer, cli_free_history(), CLI_OK, cli_unregister_all(), cli_def::commandname, free(), free_z, cli_def::hostname, cli_def::modestring, cli_def::promptchar, and cli_def::users.

void cli_error	(	struct cli_def *	cli,
		const char *	format,
			...
	)

int cli_file	(	struct cli_def *	cli,
		FILE *	fh,
		int	privilege,
		int	mode
	)

This reads and processes every line read from f as if it were entered at the console.

The privilege level will be set to privilege and mode set to mode during the processing of the file.

Parameters

cli
fh
privilege
mode

Returns

References CLI_MAX_LINE_LENGTH, CLI_OK, CLI_QUIT, cli_run_command(), cli_set_configmode(), and cli_set_privilege().

void cli_free_history

(

struct cli_def *

cli

)

Clear history array.

Parameters

cli

References free_z, cli_def::history, and MAX_HISTORY.

Referenced by cli_done(), cli_loop(), and cli_loop_free().

void* cli_get_context

(

struct cli_def *

cli

)

References cli_def::user_context.

struct cli_def* cli_init

(

ksnetEvMgrClass *

ke

)

CLI Initialize.

This must be called before any other cli_xxx function. It sets up the internal data structures used for command-line processing.

Parameters

ke	KSNet event manager class pointer

Returns

Returns a struct cli_def * which must be passed to all other cli_xxx functions.

References cli_def::auth_callback, cli_def::buf_size, cli_def::buffer, ksnetEvMgrClass::cli, cli_int_configure_terminal(), cli_int_disable(), cli_int_enable(), cli_int_exit(), cli_int_help(), cli_int_history(), cli_int_idle_timeout(), cli_int_quit(), cli_register_command(), cli_set_configmode(), cli_set_idle_timeout_callback(), cli_set_privilege(), cli_def::debug_regular, cli_def::enable_callback, free_z, ke, cli_def::ke, KSN_BUFFER_SIZE, cli_def::mode, MODE_ANY, MODE_EXEC, cli_def::privilege, PRIVILEGE_PRIVILEGED, PRIVILEGE_UNPRIVILEGED, cli_def::regular_callback, cli_def::regular_count, cli_command::system, cli_def::telnet_protocol, and cli_def::timeout_tm.

int cli_loop	(	struct cli_def *	cli,
		int	sockfd
	)

The main loop of the command-line environment.

This must be called with the FD of a socket open for bi-directional communication (sockfd).

cli_loop() handles the telnet negotiation and authentication. It returns only when the connection is finished, either by a server or client disconnect. Returns CLI_OK.

Parameters

cli
sockfd

Returns

References cli_def::auth_callback, cli_def::banner, CLI_ERROR, cli_error(), cli_free_history(), cli_loop_check_state(), cli_loop_free(), cli_loop_idle_cb(), cli_loop_read_cb(), cli_loop_select_read(), cli_loop_set_show_prompt(), cli_loop_show_prompt(), cli_loop_timer_cb(), CLI_MAX_LINE_LENGTH, CLI_OK, cli_set_configmode(), cli_set_privilege(), cli_def::client, cli_def::commands, ksnetEvMgrClass::ev_loop, free(), cli_def::idle_timeout, cli_def::ke, cli_def::last_action, malloc(), MODE_EXEC, PRIVILEGE_UNPRIVILEGED, cli_def::state, STATE_LOGIN, STATE_NORMAL, cli_def::telnet_protocol, and cli_def::users.

void cli_print	(	struct cli_def *	cli,
		const char *	format,
			...
	)

void void cli_print_callback	(	struct cli_def *	cli,
		void(*)(struct cli_def *, const char *)	callback
	)

Whenever cli_print() or cli_error() is called, the output generally goes to the user.

If you specify a callback using this function, then the output will be sent to that callback. The function will be called once for each line, and it will be passed a single null-terminated string, without any newline characters.

Specifying NULL as the callback parameter will make libcli use the default cli_print() function.

Parameters

cli
callback

References cli_def::print_callback.

struct cli_command* cli_register_command	(	struct cli_def *	cli,
		struct cli_command *	parent,
		const char *	command,
		int(*)(struct cli_def *, const char *, char **, int)	callback,
		int	privilege,
		int	mode,
		const char *	help
	)

void cli_regular	(	struct cli_def *	cli,
		int(*)(struct cli_def *cli)	callback
	)

Adds a callback function which will be called every second that a user is connected to the cli.

This can be used for regular processing such as debugging, time counting or implementing idle timeouts.

Pass NULL as the callback function to disable this at runtime.

If the callback function does not return CLI_OK, then the user will be disconnected.

Parameters

cli
callback

References cli_command::callback, and cli_def::regular_callback.

void cli_regular_interval	(	struct cli_def *	cli,
		int	seconds
	)

References cli_def::timeout_tm.

void cli_reprompt

(

struct cli_def *

cli

)

References cli_def::showprompt.

int cli_run_command	(	struct cli_def *	cli,
		const char *	command
	)

References CLI_ERROR, CLI_MAX_LINE_WORDS, CLI_OK, CLI_QUIT, cli_def::commands, and free().

Referenced by cli_file(), and cli_loop_check_state().

void cli_set_auth_callback	(	struct cli_def *	cli,
		int(*)(const char *, const char *)	auth_callback
	)

Enables or disables callback based authentication.

If auth_callback is not NULL, then authentication will be required on connection. auth_callback will be called with the username and password that the user enters.

Parameters

cli
auth_callback	must return a non-zero value if authentication is successful. If auth_callback is NULL, then callback based authentication will be disabled.

References cli_def::auth_callback.

void cli_set_banner	(	struct cli_def *	cli,
		const char *	banner
	)

Sets the greeting that clients will be presented with when they connect.

This may be a security warning for example.

If this function is not called or called with a NULL argument, no banner will be presented.

Parameters

cli
banner

References cli_def::banner, and free_z.

int cli_set_configmode	(	struct cli_def *	cli,
		int	mode,
		const char *	config_desc
	)

This will set the configuration mode.

Once set, commands will be restricted to only ones in the selected configuration mode, plus any set to MODE_ANY. The previous mode value is returned.

The string passed will be used to build the prompt in the set configuration mode. e.g. if you set the string test, the prompt will become: hostname(config-test)#

Parameters

cli
mode
config_desc

Returns

References cli_set_modestring(), cli_def::commands, cli_def::mode, and cli_command::mode.

Referenced by cli_file(), cli_init(), cli_int_configure_terminal(), cli_int_disable(), cli_int_enable(), cli_int_exit(), cli_int_quit(), cli_loop(), and cli_loop_read().

void cli_set_context	(	struct cli_def *	cli,
		void *	context
	)

References cli_def::user_context.

void cli_set_enable_callback	(	struct cli_def *	cli,
		int(*)(const char *)	enable_callback
	)

Just like cli_set_auth_callback, this takes a pointer to a callback function to authorize privileged access.

However this callback only takes a single string - the password.

Parameters

cli
enable_callback

References cli_def::enable_callback.

void cli_set_hostname	(	struct cli_def *	cli,
		const char *	hostname
	)

Sets the hostname to be displayed as the first part of the prompt.

Parameters

cli
hostname

References free_z, and cli_def::hostname.

void cli_set_idle_timeout	(	struct cli_def *	cli,
		unsigned int	seconds
	)

References cli_def::idle_timeout, and cli_def::last_action.

Referenced by cli_set_idle_timeout_callback().

void cli_set_idle_timeout_callback	(	struct cli_def *	cli,
		unsigned int	seconds,
		int(*)(struct cli_def *)	callback
	)

References cli_set_idle_timeout(), and cli_def::idle_timeout_callback.

Referenced by cli_init().

void cli_set_modestring	(	struct cli_def *	cli,
		const char *	modestring
	)

References free_z, and cli_def::modestring.

Referenced by cli_set_configmode().

int cli_set_privilege	(	struct cli_def *	cli,
		int	privilege
	)

References cli_set_promptchar(), cli_def::commands, cli_def::privilege, and PRIVILEGE_PRIVILEGED.

Referenced by cli_file(), cli_init(), cli_int_disable(), cli_int_enable(), cli_int_quit(), cli_loop(), and cli_loop_check_state().

void cli_set_promptchar	(	struct cli_def *	cli,
		const char *	promptchar
	)

References free_z, and cli_def::promptchar.

Referenced by cli_set_privilege().

void cli_telnet_protocol	(	struct cli_def *	cli,
		int	telnet_protocol
	)

References cli_def::telnet_protocol.

int cli_unregister_command	(	struct cli_def *	cli,
		const char *	command
	)

Remove a command command and all children.

There is not provision yet for removing commands at lower than the top level.

Parameters

cli
command

Returns

References CLI_OK, cli_command::command, cli_def::commands, and cli_command::next.

void void void cli_vabufprint	(	struct cli_def *	cli,
		const char *	format,
		va_list	ap
	)