Import of libcli from https://github.com/dparrish/libcli.git

Upstream commit 958e44e7a69d3c71e89908fa8ee15232c55a821a

1 files changed, 112 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..a39e115
--- /dev/null
+++ b/README
@@ -0,0 +1,112 @@
+libcli
+
+libcli emulates a cisco style telnet command-line interface.
+
+To compile:
+
+	make
+	make install
+
+This will install libcli.so into /usr/local/lib. If you want to change
+the location, edit Makefile.
+
+There is a test application built called clitest. Run this and telnet
+to port 8000.
+
+By default, a single username and password combination is enabled.
+
+Username: fred
+Password: nerk
+
+Get help by entering "help" or hitting ?.
+
+libcli provides support for using the arrow keys for command-line editing. Up
+and Down arrows will cycle through the command history, and Left & Right can be
+used for editing the current command line.
+libcli also works out the shortest way of entering a command, so if you have a
+command "show users grep foobar" defined, you can enter "sh us g foobar" if that
+is the shortest possible way of doing it.
+
+Enter "sh?" at the command line to get a list of commands starting with "sh"
+
+A few commands are defined in every libcli program:
+help
+quit
+exit
+logout
+history
+
+
+
+
+Use in your own code:
+
+First of all, make sure you #include <libcli.h> in your C code, and link
+with -lcli.
+
+If you have any trouble with this, have a look at clitest.c for a
+demonstration.
+
+Start your program off with a cli_init().
+This sets up the internal data structures required.
+
+When a user connects, they are presented with a greeting if one is set using the
+cli_set_banner(banner) function.
+
+
+By default, the command-line session is not authenticated, which means users
+will get full access as soon as they connect. As this may not be always the best
+thing, 2 methods of authentication are available.
+
+First, you can add username / password combinations with the
+cli_allow_user(username, password) function. When a user connects, they can
+connect with any of these username / password combinations.
+
+Secondly, you can add a callback using the cli_set_auth_callback(callback)
+function. This function is passed the username and password as char *, and must
+return CLI_OK if the user is to have access and CLI_ERROR if they are not.
+
+The library itself will take care of prompting the user for credentials.
+
+
+
+
+Commands are built using a tree-like structure. You define commands with the
+cli_register_command(parent, command, callback, privilege, mode, help) function.
+
+parent is a cli_command * reference to a previously added command. Using a
+parent you can build up complex commands.
+e.g. to provide commands "show users", "show sessions" and "show people", use
+the following sequence:
+
+cli_command *c = cli_register_command(NULL, "show", NULL, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL);
+cli_register_command(c, "sessions", fn_sessions, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the sessions connected");
+cli_register_command(c, "users", fn_users, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the users connected");
+cli_register_command(c, "people", fn_people, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show a list of the people I like");
+
+
+If callback is NULL, the command can be used as part of a tree, but cannot be
+individually run. 
+
+
+If you decide later that you don't want a command to be run, you can call
+cli_unregister_command(command).
+You can use this to build dynamic command trees.
+
+
+It is possible to carry along a user-defined context to all command callbacks
+using cli_set_context(cli, context) and cli_get_context(cli) functions.
+
+
+You are responsible for accepting a TCP connection, and for creating a
+process or thread to run the cli.  Once you are ready to process the
+connection, call cli_loop(cli, sock) to interact with the user on the
+given socket.
+
+This function will return when the user exits the cli, either by breaking the
+connection or entering "quit".
+
+Call cli_done() to free the data structures.
+
+
+- David Parrish (david@dparrish.com)