NAME

jumppoint - Interface wrapper to the jumppoint administration program.


DESCRIPTION

This perl module provides the interface hooks to the internals of the jumppoint system administration tool. It is *not* meant to be used with the standalone perl interpreter as it gets statically linked with the embedded perl interpreter in jumppoint. The module provides functions to access or set program configuration directives and class interfaces to the internal ssh and expect classes built into jumppoint. Note that jumppoint automatically loads these routines prior to running any other scripts, so calling use jumppoint; is not necessary.


Accessing configuration variables

The following functions provide access to jumppoint's configuration settings. You can fetch global and individual host configurations, or modify those settings from within your perl script.

To fetch a global configuration variable, use:

        $foo = get_global_setting($section, $field);

Where $section is the configuration file section and $field is the parameter name.

To set a global configuration field use:

        put_global_setting*$section, $field, $newvalue);

To save your changes into $HOME/.jumppoint/jumppoint.conf call:

        save_global_settings();

Individual host settings are accessed in a similar manner. While global settings are always available, server settings must be loaded with:

        load_server_settings($servername);

Once called, any subsequent server setting function calls will work with the currently loaded server. Calling load_server_settings() again will close the current server config and open the new one.

The following functions fetch and modify server settings:

        get_server_setting($section, $field);

        put_server_setting($section, $field, $newvalue);

        get_server_password();

        put_server_password($password);

Note the get_server_password() and sl_put_server_password(). These functions are macros that pull the value of the Password field of the Server section and automatically handle encrypting and decrypting the value. Use these functions for working with passwords unless you want to work with a bunch of goobledygook.

As with the global settings, if you make changes and want to save them, be sure to call:

        save_server_settings();

This will write the current config values to the currently open server config.


Encryption

The jumppoint module provides two functions for working with encrypted data. They are:

        encrypt_string($plaintext);

        decrypt_string($ciphertext);

These functions use your passphrase key that jummpoint prompts for before running and the builtin encryption routines. The encrypted ciphertext is also hexencoded so it can be safely written to datafiles without corrupting the textfile will non ASCII data.


SSH_Expect

The SSH_Expect class is the internal jumppoint class that is used to establish remote ssh sessions. It has built in member functions to handle automatic logins and terminal handling. To create a new SSH_Expect object within perl, use a call like this:

        $myssh = SSH_Expect->new($ssh, $hostname, $user, $pass);

Where $ssh is the full path to the ssh client program. This value can be pulled from the SSHPath field in the General section of the global config. The following example shows all the basic steps in using this class to establish an interactive remote ssh session:

        $myssh = SSH_Expect->new("/usr/local/bin/ssh", 
                             "foobar.edu", 
                             "foo", 
                             "bar");
        $myssh->connect();
        if($myssh->connected()) {
                $myssh->set_terminal();
                $myssh->interact();
                $myssh->restore_terminal();
        }

Here is a listing and description of the available member functions that can be used with this class:

        SSH_Expect->connect();

Establishes the remote connection and handles automatic logins.

        SSH_Expect->connected();

Returns true is the remote login was successful.

        SSH_Expect->send($data);

Sends the contents of $data to the remote host. This is used for running commands in a non interactive manner.

        SSH_Expect->recieve($len);

Reads in text from the remote host. The data is returned in a string. The $len argument is an integer variable specifying the maximum length of the string buffer to read in. This is a blocking read, so if you want to avoid hanging your script on a read use the following function first:

        SSH_Expect->pollpty($timeout);

This function returns true if there is data available to be read. The $timeout is the time in seconds to wait, if no data is available when the timeout expires, pollpty() will return false.

        SSH_Expect->interact();

This places the session into interactive mode, allowing the user full control of the session just like a normal login. This function loops indefinitely until the connection is terminated (e.g. by logging out).

        SSH_Expect->set_terminal();

Sets terminal handling to function in cooked mode (e.g. Backspace and escape sequences work). Note that there is currently a bug that prevents some programs from working right through this class (mainly only pico has proven troublesome).

        SSH_Expect->restore_terminal();

Places the terminal back to its original settings. Should always be called after using set_terminal.

        SSH_Expect->mask_terminal();

Blocks echoing data entered at the keyboard to standard output. Use this if you want to allow users to type in passwords that shouldn't be shown on screen.

        SSH_Expect->unmask_terminal();

Restores the terminal after a mask_terminal() call.

        SSH_Expect->noecho();

Disables all displaying of output to the terminal from the SSH_Expect object. Use this for scripts which work noninteractively to perform tasks or fetch data. Your scripts normal print statements will all appear on the terminal.

        SSH_Expect->echo();

Restores terminal settings after a noecho() call.


J_Expect

The J_Expect class is similar to SSH_Expect, except that it is a generic class which can automate arbitrary commands. Objects of the J_Expect class are declared like this:

        $myclass = J_Expect->new($cmd, \@args);

Where $cmd is the *full path* to the command you want to run and \@args is a reference to a string array of arguments. Note that the first element of \@args must be the same as the string in $cmd.

Before you can do anything with this object, you must give it the cases that it will expect from. See the expect(1) manpage for more details on writing expect patterns, since that's what jumppoint uses for its automation. The first step in adding cases to expect for is to call:

        J_Expect->set_cases($num_cases);

Where $num_cases is an integer value of the number of cases the object will expect for. Once set you can begin to add cases with the function: J_Expect->add_case($pattern, $type, $value);

$pattern is the string pattern to compare against, $type is an enumerated integer flag stating what type of expect pattern is used, and $value is the integer value J_Expect will return if the pattern is matched. The jumppoint module provides some macro names to represent the integer flags used for the $type field. They are:

        JEXP_GLOB
        JEXP_EXACT
        JEXP_REGEX
        JEXP_COMPILED
        JEXP_END
        JEXP_NULL
        JEXP_BOGUS

Of these, the only ones you should concern yourself with are JEXP_GLOB, JEXP_EXACT, and JEXP_REGEX. JEXP_GLOB sets the expect type as a shell style wildcard expression. JEXP_EXACT tells J_Expect to match the pattern exactly, and JEXP_REGEX sets the pattern as a regular expression. Note the regular expressions used with JEXP_REGEX are POSIX style regular expression, not perl regular expressions. The JEXP_END macro is used to terminate the list of expressions built up through calls to add_cases(), though you don't need to use it because J_Expect allocates space and appends it automatically. The other macro names are internal and can be ignored.

Once all your cases are added, you can begin running the program by calling:

        J_Expect->expect();

This function begins the program dialog and tries to match one of your cases. If a case is matched expect() returns the number of the expression set is the $value arguments passed in add_case(). When expect() runs out of input and doesn't find any more cases it returns 0. Normally you will call this in a loop and act on the return value like the following example:

        while($result = $myexpect->expect()) {
                if($result == 1) {
                        # Found case 1. Do something.
                        .
                        .
                }
                        .
                        .
        }

Once you are done expecting things and are ready to take control of the program this class exactly like SSH_Expect. All the member functions are the same.

Which returns true if there is data waiting to be read. The $timeout argument is the time to wait in seconds. If pollpty reaches the timeout and no data is available it will return false.

When done with a J_Expect object you should call the function:

        J_Expect->free_cases();

To free the memory allocated for your expect patterns. The object will take care of this when it is destroyed, but it is a good habit to call this yourself, especially if you wish to reuse the object.


RUNTIME FUNCTIONS

The jumppoint perl module provides several functions that may be used in subroutines called from the GUI at runtime. These functions should not be used in scripts that are run standalone from the command line.


Input and Output from the GUI

The following functions deal with fetching input and displaying output in the GUI.

        $result = gui_prompt($message, $default);
        $result = gui_pass_prompt($message, $default);

Prompts the user in a GUI pop up window. The $message is displayed and $default is the default value. The function returns the text entered into the dialog by the user. gui_pass_prompt() is identical to gui_prompt() with the exception of the texted typed into the dialog is masked in a password textbox.

        $res = gui_ask($question);

Prompts the user with a pop up window displaying the contents of $question with Yes and No buttons. Returns 1 if Yes was clicked, otherwise returns 0.

        gui_alert($message);
        gui_message($message);
        
These functions open a pop up window displaying the contents of C<$message> 
and a button to close the window. C<gui_message()> just displays an 
informational message while C<gui_alert()> also sounds an annoying bell.

  show_file_chooser($label, $pattern, $default);

The show_file_chooser() function will display the FLTK file browser. The $label argument is the label to place in the file chooser window, $pattern is the file pattern to use to filter the list of files, and $default is a default file selection to use. This function returns a string containing the path to the selected file.

  log_message($message);
  log_warning($message);
  log_error($message);

These functions print output to the status browser view on the left side of the main jumppoint window. log_message() with print the contents of $message in plain text, log_warning() will print as bold text, and log_error() will print bold italic text with a red bullet in front of the message.

  send_status($message, $event);

The send_status() function is similar to log_message(), however it allows you to map an event to the item. When this function is used, if the user clicks on the item in the status browser, jumppoint will eval the contents of $event.


Menus

The following two functions allow you to extend the menus on the main jumppoint window. add_menu_item($label, $shortcut, $event); add_server_menu($label, $event);

The add_menu_item() function adds an item to the main menu of jumppoint, while add_server_menu() adds the the pop up menu of the server browser. The $label argument of each function can specify the subfolder as well as the label name. For example, by passing the value 'My Stuff/My Item' to add_menu_item() and menu item called My Item will be created under the My Stuff subfolder. If the subfolder does not exist it will be created. Note that the $shortcut argument of add_menu_item() is currently disabled, so you should pass that argument a blank string.

Making additions to the menu should happen during initialization. When jumppoint starts it initializes the interpreter, loads the core modules, builds the GUI objects, then parses the system menu.cfg and the user's menu.cfg file if available. It then loads any user defined modules before actually showing the main window. Any menu additions you wish to perform should occur within a BEGIN block of your module.


Additional GUI Events

This section contains descriptions of additional miscellaneous functions used by jumppoint when using the GUI mode. Many of the functions here should be catagorized elsewhere, but have been stuck here cuz I'm a lazy SOB and am procrastinating.

  current_servername();

This function returns the hostname of the currently selected server from the server list.

        $child = new_session($command);

This function will pass the command string in $command and instruct jumppoint to open a new xterm and run the command. Jumppoint will return the pid of the new process to the function. The child process will be cleaned up by jumppoint when it terminates, so no special handling is needed.

The following functions are core callbacks. These functions invoke some of the basic functions standard in jumppoint. They are here for reference should you decide to replace the system menu.cfg with one of your own.

        show_connect();

This is one of the core callback routines and will display the built in connection dialog box.

        show_scp_window();

This is a core callback that displays the scp file transfer window.

  show_about();

Displays the about jumppoint window.

        show_preferences();

This function displays the built in preferences dialog box.

        exit_gui();

This callback closes jumppoint.


BUGS

Some programs (pico), do not function well with the expect classes' terminal handling. Real editors like vi work fine though ;)


AUTHORS

Matt Kennedy <matt@jumpline.com>


SEE ALSO

expect(1) regex(7)