|
1 | | -libcli |
| 1 | +Libcli provides a shared C library for including a Cisco-like command-line |
| 2 | +interface into other software. |
2 | 3 |
|
3 | | -libcli emulates a cisco style telnet command-line interface. |
| 4 | +It’s a telnet interface which supports command-line editing, history, |
| 5 | +authentication and callbacks for a user-definable function tree. |
4 | 6 |
|
5 | 7 | To compile: |
6 | 8 |
|
7 | | - make |
8 | | - make install |
| 9 | +```sh |
| 10 | +$ make |
| 11 | +$ make install |
| 12 | +``` |
9 | 13 |
|
10 | | -This will install libcli.so into /usr/local/lib. If you want to change |
11 | | -the location, edit Makefile. |
| 14 | +This will install `libcli.so` into `/usr/local/lib`. If you want to change the |
| 15 | +location, edit Makefile. |
12 | 16 |
|
13 | | -There is a test application built called clitest. Run this and telnet |
14 | | -to port 8000. |
| 17 | +There is a test application built called clitest. Run this and telnet to port |
| 18 | +8000. |
15 | 19 |
|
16 | 20 | By default, a single username and password combination is enabled. |
17 | 21 |
|
| 22 | +``` |
18 | 23 | Username: fred |
19 | 24 | Password: nerk |
| 25 | +``` |
20 | 26 |
|
21 | | -Get help by entering "help" or hitting ?. |
| 27 | +Get help by entering `help` or hitting `?`. |
22 | 28 |
|
23 | 29 | libcli provides support for using the arrow keys for command-line editing. Up |
24 | 30 | and Down arrows will cycle through the command history, and Left & Right can be |
25 | 31 | used for editing the current command line. |
| 32 | + |
26 | 33 | libcli also works out the shortest way of entering a command, so if you have a |
27 | | -command "show users grep foobar" defined, you can enter "sh us g foobar" if that |
| 34 | +command `show users | grep foobar` defined, you can enter `sh us | g foobar` if that |
28 | 35 | is the shortest possible way of doing it. |
29 | 36 |
|
30 | | -Enter "sh?" at the command line to get a list of commands starting with "sh" |
| 37 | +Enter `sh?` at the command line to get a list of commands starting with `sh` |
31 | 38 |
|
32 | 39 | A few commands are defined in every libcli program: |
33 | | -help |
34 | | -quit |
35 | | -exit |
36 | | -logout |
37 | | -history |
38 | | - |
39 | | - |
40 | 40 |
|
| 41 | +* `help` |
| 42 | +* `quit` |
| 43 | +* `exit` |
| 44 | +* `logout` |
| 45 | +* `history` |
41 | 46 |
|
42 | 47 | Use in your own code: |
43 | 48 |
|
44 | | -First of all, make sure you #include <libcli.h> in your C code, and link |
45 | | -with -lcli. |
| 49 | +First of all, make sure you `#include <libcli.h>` in your C code, and link with |
| 50 | +`-lcli`. |
46 | 51 |
|
47 | 52 | If you have any trouble with this, have a look at clitest.c for a |
48 | 53 | demonstration. |
49 | 54 |
|
50 | | -Start your program off with a cli_init(). |
| 55 | +Start your program off with a `cli_init()`. |
51 | 56 | This sets up the internal data structures required. |
52 | 57 |
|
53 | 58 | When a user connects, they are presented with a greeting if one is set using the |
54 | | -cli_set_banner(banner) function. |
55 | | - |
| 59 | +`cli_set_banner(banner)` function. |
56 | 60 |
|
57 | 61 | By default, the command-line session is not authenticated, which means users |
58 | 62 | will get full access as soon as they connect. As this may not be always the best |
59 | 63 | thing, 2 methods of authentication are available. |
60 | 64 |
|
61 | 65 | First, you can add username / password combinations with the |
62 | | -cli_allow_user(username, password) function. When a user connects, they can |
| 66 | +`cli_allow_user(username, password)` function. When a user connects, they can |
63 | 67 | connect with any of these username / password combinations. |
64 | 68 |
|
65 | | -Secondly, you can add a callback using the cli_set_auth_callback(callback) |
66 | | -function. This function is passed the username and password as char *, and must |
67 | | -return CLI_OK if the user is to have access and CLI_ERROR if they are not. |
| 69 | +Secondly, you can add a callback using the `cli_set_auth_callback(callback)` |
| 70 | +function. This function is passed the username and password as `char *`, and must |
| 71 | +return `CLI_OK` if the user is to have access and `CLI_ERROR` if they are not. |
68 | 72 |
|
69 | 73 | The library itself will take care of prompting the user for credentials. |
70 | 74 |
|
71 | | - |
72 | | - |
73 | | - |
74 | 75 | Commands are built using a tree-like structure. You define commands with the |
75 | | -cli_register_command(parent, command, callback, privilege, mode, help) function. |
| 76 | +`cli_register_command(parent, command, callback, privilege, mode, help)` function. |
76 | 77 |
|
77 | | -parent is a cli_command * reference to a previously added command. Using a |
| 78 | +`parent` is a `cli_command *` reference to a previously added command. Using a |
78 | 79 | parent you can build up complex commands. |
79 | | -e.g. to provide commands "show users", "show sessions" and "show people", use |
| 80 | + |
| 81 | +e.g. to provide commands `show users`, `show sessions` and `show people`, use |
80 | 82 | the following sequence: |
81 | 83 |
|
| 84 | +```c |
82 | 85 | cli_command *c = cli_register_command(NULL, "show", NULL, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL); |
83 | 86 | cli_register_command(c, "sessions", fn_sessions, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the sessions connected"); |
84 | 87 | cli_register_command(c, "users", fn_users, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the users connected"); |
85 | 88 | cli_register_command(c, "people", fn_people, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show a list of the people I like"); |
| 89 | +``` |
86 | 90 |
|
87 | | - |
88 | | -If callback is NULL, the command can be used as part of a tree, but cannot be |
| 91 | +If callback is `NULL`, the command can be used as part of a tree, but cannot be |
89 | 92 | individually run. |
90 | 93 |
|
91 | | - |
92 | 94 | If you decide later that you don't want a command to be run, you can call |
93 | | -cli_unregister_command(command). |
| 95 | +`cli_unregister_command(command)`. |
94 | 96 | You can use this to build dynamic command trees. |
95 | 97 |
|
96 | | - |
97 | 98 | It is possible to carry along a user-defined context to all command callbacks |
98 | | -using cli_set_context(cli, context) and cli_get_context(cli) functions. |
| 99 | +using `cli_set_context(cli, context)` and `cli_get_context(cli)` functions. |
99 | 100 |
|
100 | 101 |
|
101 | 102 | You are responsible for accepting a TCP connection, and for creating a |
102 | 103 | process or thread to run the cli. Once you are ready to process the |
103 | | -connection, call cli_loop(cli, sock) to interact with the user on the |
| 104 | +connection, call `cli_loop(cli, sock)` to interact with the user on the |
104 | 105 | given socket. |
105 | 106 |
|
106 | 107 | This function will return when the user exits the cli, either by breaking the |
107 | | -connection or entering "quit". |
108 | | - |
109 | | -Call cli_done() to free the data structures. |
| 108 | +connection or entering `quit`. |
110 | 109 |
|
| 110 | +Call `cli_done()` to free the data structures. |
111 | 111 |
|
112 | | -- David Parrish (david@dparrish.com) |
0 commit comments