BatchLogin Command Line Reference



BatchLogin is a powerful tool for executing automation across diverse Unix server environments. It began life as a way to shave time on a project where access to a group of servers was prohibitively complex. Part of that complexity was due in part to extremely good security.

As things get more secure, the inevitably get more complex. An extremely secure environment culminates upon a holy grail where nothing can be done and no services are rendered because all of them have been firewalled off from the end users. Well, there's one final step beyond that, and that involves powering off the server, but at that point we're splitting hairs.

You get the idea, things get more secure, it becomes harder to access a box.

Complicating matters in any complex environment is the fact that diversity becomes an issue; it isn't just that an end user must go through several hoops to get from point A to point C, it's the fact that going to point D or B is an entirely different series of steps.

BatchLogin strives to document these steps and provide a local "vault" that belongs strictly to the end user. These "vaults" are called passlists. Passlists document authentication "hops" and other items with a simple end goal: get a shell prompt, at some user level needed (and documented), on a remote machine.

Once the user has control over a virtual list of shell prompts, many things can happen:

All of these things are accomplished with two user interface programs: BL2 and BLT2. BL2 is the main setup program. It controls passlists and allows complex sessions to be started. BLT2 offers a quick shortcut to BL2 functionality: it executes the "SHELL.exp" program on a small list of servers provided on the command line.


BL2 is accessed from the server where it is installed with the shell command "bl2". Initial setup for this utility is somewhat complex, and covered elsewhere. Essentially, to begin running BatchLogin, a user must have at least one password list (passlist) and at least one script to execute (the SHELL.exp script is provided as an example expect script starting point, and to enable BLT2 functionality).

A Simple Example: Log into every server on a passlist

paul on voidville at /home/paul
# bl2
1) [ABORT]                5) LASTLOG                9)
2) CRYPT_PROGRAM          6) LOGS
3) GUI                    7) DEBUG
4) GROUPS                 8) SHELL.exp

Note that BL2 starts with a menu that offers a bunch of options, and some scripts (found in the "~/.batch2/scripts" directory. The menu options shown here are for a user (paul) who has two scripts, SHELL.exp and

The menu options are fairly self-explanatory, but here's a quick rundown:

  1. [ABORT], end the program.
  2. CRYPT_PROGRAM, Create/view/edit password lists (passlists).
  3. GUI, Launch a Java utility for the keyboard impaired.
  4. GROUPS, manage group control files. (text files that control subsets of password lists).
  5. LASTLOG, view the last log file created by last run of the program.
  6. LOGS, peruse log files.
  7. DEBUG, toggle debug mode on or off.
From there the menu lists scripts that can be executed. Scripts should end in .exp or .sh. It's entirely up to the user and not strictly enforced. Expect scripts have to end in ".exp", or the program will assume, stupidly, that the user wishes to execute the code as shell code and likely ugly, unintended things will happen. Keep hands and feet away.

This menu changes when the user signals the intent of executing some program by selecting the number corresponding. For example, if the user (paul) selects "SHELL.exp", which is an expect program provided at initial setup that simply executes a login onto the box, the menu changes. In effect, BatchLogin asks the user which passlist to apply the script.

Select script to execute: 8
1) [ABORT]
2) home.blf
Select server/password list:

This user only has one password list, called "home.blf". The choice is simple, in other words:

RACF used will be paul

## BatchLogin Version 2.0
## Logfile /home/paul/.batch2/logs/2004/03/27/log_19475.log
## Outfile /home/paul/.batch2/logs/2004/03/27/run_SHELL_home_19475.log
## Script  SHELL.exp
## Control home.blf

Control file home.blf added.

Enter password to unlock home.blf:
At this point, BatchLogin is prompting for the password on the password list home.blf. Paul enters the password for that file.
Loading authentication array.
Shell spawn PID=19489 successful.
MAILROOT: executing hop 1 of 2 [MAIL:]
Connecting as user paul on node mail.vv
MAILROOT: executing hop 2 of 2 [MAILROOT:]
Switch user to root on node [-]
Logged in.  Label=MAILROOT:
entering interactive mode, type ^^ (two carets) when done.
don't log out while interactive, the script will get confused
root on tim at /
At this point, the program has attached to a remote node (tim), and has turned control back over to the user. Paul can execute any command as root from here, and to continue on to the next node, simply type two caret keys, in sequence (^^). The setup for these characters can be altered to be any key combination. Two carets was chosen arbitrarily.

Note that it is undesirable to log out of the node (tim), as the program keeps track of hops, both in and out of a machine. Executing an exit, in other words, on a remote node, will definitely confuse BatchLogin. It's best to return to a shell prompt and hit the two carets to continue. This takes some getting used to.

The user is done on node tim, so they hit the two carets:

MAILROOT: executing drop 1 of 2 [MAILROOT:]
MAILROOT: executing drop 2 of 2 [MAIL:]
Shell spawn PID=19513 successful.
GWROOT: executing hop 1 of 2 [GW:]
Connecting as user ferripi on node gw.vv
GWROOT: executing hop 2 of 2 [GWROOT:]
Switch user to root on node [-]
Logged in.  Label=GWROOT:
entering interactive mode, type ^^ (two carets) when done.
don't log out while interactive, the script will get confused
root on straylight at /
Note that the program attempts to drop out of the connection in the reverse order of the entry. In the above example, the program has logged into a second machine (straylight). It's all pretty much the same from here. The user continues on in this fashion until they have logged into every machine in the password list (home.blf). Used in this manner, the program allows for a quick "tour" of a group of machines in a password list.

This is a very basic usage of BatchLogin. It's power lies in the ability to script something and execute it the same way -- instead of logging in, imagine doing something complex, like checking for a specific hardware condition, disk space problems, uptime issues. Whatever can be done with a simple shell script can be easily executed by BatchLogin, as simply as shown in this small example.

To accomplish simple script execution, all the user has to do is create the script in their scripts directory, and select the script instead of SHELL.exp at run-time. The results of the run are logged into a file (As is everything that BatchLogin is doing, except for passwords.


BLT2 came into existence after BatchLogin. BLT stands for Batch Login Terminal (and other, obvious things), the version 2.0 program adds a "2" at the end. To execute the program, the user should have the same prerequisites as a BatchLogin session (one passlist and at least the SHELL.exp program).

To understand why BLT came into being, a little history is in order. BatchLogin was initially created to log, in mass, into a group of servers.

The basic idea for BLT2 came about after the inception of BatchLogin, where the author realized that one of the most powerful things that the program was really doing for the user lies in the documentation of connection. In other words, it took a lot of the pain out of getting from point A to point C. Suddenly it was possible to log into 100 servers at once.

Unfortunately, it wasn't possible (before BLT) to get to just one of those servers without going through the same pains as before (secure shell here, dig through the deep recesses of the brain for a password, secure shell there, use another password, open an excel spreadsheet, curse, call this or that admin, have password reset, and so on). When BatchLogin emerged, it was realized that the encrypted file didn't just allow access to a big long list of servers, it documented precisely how to get to each server -- and this itself was a value.

BLT2 was born. BLT2 is a short-circuit into BatchLogin's shell capability. The syntax is similar to a typical connection program:

# blt2 [server]
But the [server] parameter above is actually a label reference. This means that the user can name a server (or an id, on a server, such as wasadm4) a name that means something unique and more sensible. For example, a adm7 account on one of the servers could be (hypothetically) attached to with the following:
# blt2 adm7lb:
While that might look like a mess to a general observer, the name is up to the user, and it means that it's possible to name connections to boxes with labels that are far more intuitive, thus taking the pain (and indirection of thought) out of a connection to a particular environment.

It's also possible to have blt2 spawn several connections at once. Suppose that a load balanced environment has 4 servers in an array, and the user needs to log into all of them with the adm7 account (in this case, they've named the connections adlb[n], where n is 1-4:

# blt2 adlb1 adlb2 adlb3 adlb4

Or, alternatively, they could use the "GROUPS" selection from bl2, and create a group for the above (named, in this case, "loadbalanced"). The group definition file looks like this:

# File name ~/.batch2/passlists/loadbalanced_group.txt
passlist loadbalanced.blf
comment load balanced servers
label adm7NODE21:
label adm7NODE11:
label adm7NODE21:
label adm7NODE11:
What this does is designate a group of labels inside of the loadbalanced.blf password list that are endpoint connections. Now instead of blt2-ing to a list of 4 servers to open 4 terminal windows to these boxes, the user instead simply types:
# blt2 loadbalanced
The end result, after entering the password for loadbalanced.blf, is a group of terminal windows, open to all 4 servers, logged in as adm7.


As indicated in this document, a passlist is a list of connections to a group of servers. It's really a bit more than that, as it contains some rather sensitive information (possibly your login credentials on a group of servers). It's possible that the list can contain a lot of sensitive information, so you should make sure that the password you choose to protect your list is not shared, and since the encryption (blowfish) is rather hard to crack, if you loose the password, you've more or less lost your list as there's no way to get it back.

You can learn more about the configuration of a passlist by studying the configuration.html specification page. Some things that are exciting:

Password lists document not just what username/password is required to authenticate, they also document how to get to a particular environment. This is the real power of BatchLogin -- the ability to leave the thought about a connection methodology to a program, and free the users' mind for things like what is going to transpire when connected.

Scripts and Logs

The basic ability of shelling into a server is one thing, the ability to execute automated tasks and gather general statistics across a broad range of servers is another. BatchLogin can do both. The method it uses to accomplish this is extremely basic. Once it obtains a login on a particular server, it creates a script in /tmp using the shell account with the most general of Unix commands (cat, actually).

The reasons for this may not be obvious, so they're outlined here:

In other words, BatchLogin never fails to get the script there and execute it. As your network environment evolves, as it gets more segregated, as the layers increase, these features will still be there, no matter what happens.

Scripts go in the user's ~/batch2/scripts directory. At run time, the nodename (uname -n, to be exact) is passed to the running program. This makes it easy to gather data from the log file created from the session.

For example, maybe the user needs to check the uptime of a batch of servers defined in a passlist. They create a script that looks like this:

# Script: ~/.batch2/scripts/
echo "DATA $1 $(uptime)"
They fire BatchLogin, select the "" script, select the passlist, and bl2 executes the script across a the range of servers defined in the file. Then, once the run completes, they issue the following command:
bl2 cat | grep "^DATA"
This shows just the lines from the log file that were created when the script ran, and since the node name is passed as the first parameter, the results are obvious.

Where To Go From Here

Setup of BL2 takes some time. At the beginning, it's not all that intuitive. After the first couple of servers, however, it becomes something of a second nature. The frustration comes when a server's connection is not documented in a passlist. Since BatchLogin takes the pain out of connecting to a server, the motivation to have the setup overcomes the initial pain.

The long-term result is simplicity: passwords are easy to update, jumps to servers are well documented, and the user can concentrate on the work at hand, not the steps required to get to the work. This is the real power of the program.

Special notes:

The BatchLogin process is not magic (although at times, it seems to act in mysterious ways), it's really doing what humans do when they log in, only at extremely high speed. It's "watching" the screen for expected prompts. This brings up an extremely important point: Your prompt has to be something that BatchLogin recognizes.

BatchLogin looks for typical prompt characters: # $ and > followed by a space. If you have a connection that doesn't seem to work with BatchLogin, take a close look at the prompt. For not so obvious reasons, colons are not recognized as a prompt. The reason is because the colon appears all over the place (login:, password: , The date is 10:05), it's not supported as a prompt.

It's extremely important that the prompt end with one of the supported characters (#, $, >), and a space. It's that simple. There have been requests to alter the program to work without the space, and it's simply not possible due to the way that these items are utilized in our environment.

Command Line Switches

BatchLogin Command Line Switches and Options
last Open the last log file with vi lr | rl | lastrun Open the last log file with vi lm Bring up the log perusal menu. tail tail (with -f, or follow) the latest log file. cat cat the latest log file to standard out. clean Attempt to clean the latest log file to stdout. -x Toggle the display variable off when the program starts. -d Toggle the debug variable on when the program starts. PARM1Match a script for execution. PARM2Match a passlist for execution.
So for example, utilizing the above table, it's possible to launch a SHELL.exp session to a group of AIX servers, with Xwindow display turned off by starting bl2 with these flags (This assumes the user has an AIX.blf file):
# bl2 -x SHELL.exp AIX
Order is important, it's just like the order of the menu program. Options passed the program must match one and exactly one script or passlist. So, for example, should the user executing the above command have two passlists, AIX.blf and AIXb.blf, the program will yelp about ambiguity, and present the user with the usual lame menu.