What is a personality?
A personality tells opConfig (or more precisely, the lower-level module Net::Appliance::Session) how to interact with a device, how to know when the connection is ready for the username or password, how to enter privileged mode, what state the current connection is in, and so on.
Personalities are defined by phrasebooks, the name of the folder containing the phrasebook defines the name of the personality.
What is a phrasebook?
A phrasebook is a file named "pb" that contains a list of prompts and macros, and the name of the directory the phrasebook resides in will be its personality name. Phrasebooks may be built up hierarchically from data in multiple subdirectories; e.g. a phrasebook "deeper down" in the hierarchy has the ability to override settings loaded from the parent other directories "higher up".
Eg.
unix/pb <- may contain a whole or partial phrasebook
unix/bash/pb <- contains everything in unix/pb, anything in this pb will override unix/pb
unix/csh/pb <- contains everything in unix/pb, anything in this pb will override unix/pb
Macros define specific tasks that opConfig needs to perform, like entering privileged mode, exiting privileged mode, disconnecting or adjusting the pager.
Prompts have specific names like user, pass, generic and privileged that are mapped to regular expressions, when a regular expression matches opConfig it assumes it is at that prompt.
One very important thing to bear in mind:
- You must not save any files except the desired phrasebook in a phrasebook library directory.
If a phrasebook directory contains any other files (e.g. a backup of a phrasebook file created by your editor), then the Net::Appliance::Session module will load these files as well.
Depending on the file ordering the bad files will likely override some or all of the configuration that you put into your "real" phrasebook file.
Phrasebook macros and prompts
| Prompts | |
|---|---|
| prompt user | regular expression, when matched opConfig will assume the terminal is expecting a username to be entered |
| prompt pass | regular expression, when matched opConfig will assume the terminal is expecting a password to be entered |
| prompt generic | regular expression, when matched opConfig will assume the terminal is at a normal, non-privileged prompt |
| prompt privileged | regular expression, when matched opConfig will assume the terminal is at a privileged prompt, eg. enabled mode or having root access |
| prompt connection_error | regular expression, when matched opConfig signals the terminal connection has an error |
| Macro | |
|---|---|
| macro begin_privileged | commands to send to enter privileged mode, followed by the prompt to expect |
| macro end_privileged | commands to send to exit privileged mode, followed by the prompt to expect |
| macro disconnect | commands to send to end the terminal session |
| macro paging | commands to change the pager |
Creating a new phrasebook
To create a new phrasebook, make a new directory in the phrasebooks directory hierarchy, and place a text file named pb inside of it. You now have a new personality/phrasebook with the name of the new directory that was created. If the directory was created at the base of the hierarchy the pb is truly empty and defines nothing, if it was in a subdirectory then the pb currently has the contents of the base directories pb.
The next step is to determine what should be in the phrasebook, this is the difficult part.
Here is an algorithm to solve the problem.
Add a node to opConfig, set the personality to the new personality created, set the transport and credentials to be correct.
While not working do these steps:
- Attempt a test_connect to the node in question (debug=9 is important here)
- /usr/local/omk/bin/opconfig-cli.pl act=test_connect node=NODE_NAME debug=9
- Inspect the debug output, (it may work best to pipe the output to a file for inspection)
- the bottom line may give you information about the problem, eg:
- Error, connection test returned "Authentication Error", error message "login failed to remote host - prompt does not match"
- Look top down, attempting to figure out how far the terminal session got
- Look for lines like, they indicate prompts working and macros being run:
- [ 3.095807] pr hit, matches prompt pass
- [ 3.994504] pr hit, matches prompt generic
- [ 4.264275] en running macro begin_privileged
- Look for lines like, they indicate prompts working and macros being run:
- You should now have a bit of an idea how far the connection attempt got
- Now look bottom up for where it failed, search for "pr failed:" or scroll through and look where the same output starts repeating, eg:
-bash-4.1$
[ 4.475526] pr nope, doesn't (yet) match connection_error
[ 4.475725] pr nope, doesn't (yet) match generic
[ 4.475914] pr nope, doesn't (yet) match pass
[ 4.476100] pr nope, doesn't (yet) match privileged
[ 4.476274] pr nope, doesn't (yet) match user
[ 4.476398] pr no match so far, more data?
[ 15.478110] pr failed: [read timed-out at /usr/local/ActivePerl-5.16/site/lib/Net/CLI/Interact/Transport/Wrapper/Net_Telnet.pm line 35
- Now figure out which prompt is failing to match, or which macro command is not working (eg, sudo -Hi bash may not work on your server but su - will)
- Change the prompt or macro, go back to step 1
A successful connection means you have a phrasebook that works.
At this time discovery will not attempt to use the new personality, you will have to edit each node that uses this personality. For this reason you may want to consider modifying the stock personalities if all of your devices react the same way.
More information
see http://search.cpan.org/~oliver/Net-CLI-Interact-2.200002/lib/Net/CLI/Interact/Phrasebook.pm