Actor Documentation

Use the Sourceforge project page for downloads. This documentation is included in all downloads.

Shameless Self Promotion
What Is Actor
Why Use Actor
Additional Features Of Actor
Actor Setup
A Short Tutorial
Continuous Integration With Ant
Running Scripts On Remote Servers
A Tour Of The Actor::modules
Logging And Trouble Shooting
Additional Documentation

Actor Authored by Laurence Clark--hsuclarklarry@sbcglobal.net
So far, I am the sole author of Actor. Actor is my gift to over worked System Engineers. I am happy to support you for free as time allows.

View My Resume

Actor provides a web-enabled, self-service user interface to run your scripts. You run a small but complete desktop application to control access to your scripts. Your users get a web site where they select from options you setup. After selecting options, users may run the scripts on-demand or from a continuous integration environment such as Cruise Control.

So you have some scripts to run. Why do you need Actor to run them? Actor does the hard stuff. You do the easy stuff. Writing scripts is easy. Writing a web-enabled, self-service user interface for your scripts is a little harder. Writing scripts that never fail is a kind of hard. With twenty years of experience coding server-side, multi-process software applications, I know how to run your scripts so they never fail:

Web Application On An Easily Accepted Platform
That team of Java developers you are supporting does not need to hear that you can replace a thousand lines of their Java code with one line of Perl or Python. All they see of Actor are JSPs and Java Servlets running in Apache-Tomcat or some other familiar Servlet container.

Fail-Safe Back End
Carefully limited technology choices on the back end --Perl DBI with MySQL on Linux--avoid any hint of instability. Note that Actor's Java web application does not run your scripts! The job of running commands from the request queue is left to a thousand or so lines of time-tested carefully crafted Perl code.

One Script At A Time
Every publication I've read on scripting, addresses the problem of running two instances of your script at the same time. You can save the textbook solution for job-interviews. Actor solves the problem for you by queuing requests and running them one at a time.

Separate Processes
Actor forks separate processes; to run your script, to capture and log its output and if your script times out, Actor will kill every child process, report every error code and log all available output.

Run Scripts On Remote Servers Reliably With SSH
Actor can run your scripts on remote servers using ssh. Actor captures the process id of your script on the remote server and uses it to clean up in case of a timeout. To improve security Actor never needs to make an ssh connection as "root." Actor automatically sets up "sudo" permissions to run each required command.

Time Outs
You define timeouts for your scripts when you set them up in Actor. Before the timeout Actor causes your script to ignore common signals but when the time is up, Actor will clean up by killing your script and all its child processes.

Thorough Painstaking Cleanup Of Resources
When the time comes, Actor will eliminate every child process using strategies that are reasonably simple but proven over time on heavily loaded production servers.

Thorough Painstaking Error Reporting
When a child process in Actor exits abnormally you will get a complete error messages--not just the exit codes but a human readable description of the process and the line of code where the process started. This is just one example of the care I have taken in reporting problems with Actor or problems with your scripts.

Fail-Safe Logging
Logs are useless if they are not available when the application fails. I have made a study of ensuring that I capture and log all output from your scripts as well as all problems with Actor.

Light Weight
Actor has just the features you need to enable fail-safe self-service access to your scripts. No other features are included. I plan to release more Actor::modules but the core of Actor will remain lean. If you are looking for a full featured system administration tool then Actor is not for you.

Mobile Ready
Actors simple web interface works well on mobile devices. Most pages are under 500 pixels wide. Turn your iphone sideways and this size fits great. A previous manager of mine liked to say, "I'm no longer afraid to leave the building. I can restart the web-server from my cell phone."

Actor has three components; Producer, Consumer and Agent. Producer is the web application that your users will see. Users make requests with Producer that are saved to a MySQL database. Consumer reads the requests from the database and executes them. Agent is the application used by you, the administrator, to customize Actor.

Each of the three actor components has its own unique requirements. So different technologies are used to optimize each component. Producer, the web application, uses Java servlets and JSPs. Producer was developed and tested with Apache-Tomcat but it should be compatible with other servlet containers. Consumer, the back end, runs as a service/daemon written in Perl. Finally Agent, the admin application, runs Qt widgets from Python code.

LINUX OS
So far, Actor has been developed and tested on a community operating system that should guarantee compatibility with Redhat Enterprise 5. I am confident that Actor will work well on other Linux distributions and would be happy to support them.

JAVA JSPS AND SERVLETS
To use Actor you need to be running Apache-Tomcat or some other Java Servlet container. The binary release of Cruise Control runs from Jetty, an embedded servlet containter and Actor has been tested with this setup as well as with Tomcat. Setup directions for Tomcat are beyond the scope of this document. However, I would be happy to support early adopters of Actor on an individual basis.
Actor has been tested with;
java version "1.6.0_11"
apache-tomcat-6.0.18 and
cruisecontrol-bin-2.8.2

GRAPHICAL USER INTERFACE WITH PyQt
Actor-Agent needs to display a graphical user interface. There are many choices about how this can happen on Linux or Windows. The bottom line is that your Actor Server DOES NOT need to be running a GUI. All my testing is done on "headless" Linux servers. My test servers may have X-Windows installed but they boot to "run level 3" (no graphics). Agent uses PyQt version 3.16 with Python 2.4.3. These are standard versions for RHEL5. So the Redhat install is simple:
yum install PyQt

MySQL
Tested with the standard RHEL5 mysql package version 5.0.45-7.el5.
yum install mysql-server

PERL
Actor needs Perl 5.8. It's pretty unusual to setup a Linux release without Perl 5.8. So you should be ok here.

PERL MODULES
Actor uses only a couple of modules outside of the Perl Core. First we need perl-DBI to access our MySQL database. On Redhat we can install with yum like this:
yum install perl-DBI perl-DBD-MySQL

Install the module Log::Log4perl using the CPAN shell. The first time you run the CPAN shell you will need a few minutes to answer some setup prompts. Since you are interested in scripting this is time well spent. To install use the following commands:
perl -MCPAN -eshell
install Log::Log4perl
quit

You will need Apache-Ant installed:
ant.apache.org

Download actor_0.3.2_src.tgz and extract the contents. "cd actor_0.3.2" and run ant. This will build a tar file matching the binary download.

So, we have a Redhat server ready to go with all the above requirements: Linux, Apache-Tomcat, MySQL Server, Perl and Python with PyQt. Perl has database access with the DBI module and logging with Log4perl. Finally we have downloaded the binary distribution or we have built it from source. Put the binary distribution tar file--call it actor_0.3.2.tgz--into /root and lets setup Actor.

The following instructions are suitable for pasting into a terminal on a Redhat server. Directions that are not Linux Shell commands have been added as shell comments starting with the # character. I use variables with ALL_CAP names for values that you will need to edit for your server.

#
# AS root ON THE NEW ACTOR SERVER
#

# extract the tar file
cd
tar -zxf actor_0.3.2.tgz

#create the database
service mysqld start
mysql
drop database if exists actor;
create database actor;
grant all privileges on actor.* to actor@'%' identified by 'rotca';
use actor;
source /root/actordb_0.3.2.dump;
quit;

# update data and script for current version
chmod +x consumer_0.3.2/setup/setup4version.sh
consumer_0.3.2/setup/setup4version.sh

# Setup the actor service to run consumer
cp consumer_0.3.2/setup/slash_etc_init.d/actor /etc/init.d

chmod +x /etc/init.d/actor
find consumer_0.3.2 -iname '*.pl' | xargs chmod +x
chkconfig --add actor
service actor start

# install the web app
TOMCAT_INIT=/etc/init.d/tomcat6
CATALINA_HOME=/usr/apache-tomcat-6.0.18
WEBAPPS=$CATALINA_HOME/webapps/
CONF=$CATALINA_HOME/conf
mv producer_0.3.2 $WEBAPPS

# Log files are written to Apache httpd standard location.
# Create a link for tomcat-only setup.
cd $WEBAPPS
ln -s /var/www/html/actor

vim $CONF/web.xml
# Add the following with the other mime mappings.
<mime-mapping>
<extension>log</extension>
<mime-type>text/plain</mime-type>
</mime-mapping>

# restart tomcat
$TOMCAT_INIT stop
$TOMCAT_INIT start

#
# We can now log on to the webapp.
# http://myactorserver:8080/producer_0.3.2
# Login admin
# Password admin
#

#
# ON OUR GUI SERVER
# If our web-server has X-windows installed,
# we can continue on the same server.
#
#

# Extract agent from actor.tgz
cd
[ -e agent_0.3.2 ] || tar -zxf actor_0.3.2.tgz agent_0.3.2

# Edit settings to connect to the correct version
# of producer on myactorserver.
vim agent_0.3.2/settings.py
self.wsurl='http://myactorserver:8080/producer_0.3.2/xmlrpc'

# Create a script to run agent.
cd
[ -e bin ] || mkdir bin
cat > bin/agent.sh <<eof
#!/bin/bash
$(which python) $HOME/agent_0.3.2/formmain.py >& /dev/null
eof
chmod +x bin/agent.sh

Lets run Agent, "agent.sh", and setup a new command for the default user. From Agent press "Edit Command Types." Press "Clear" and enter "Sys Admin--Basic" for "Display Name." Press "Save as New" to create the new command type. Return to the main window and press "Copy Command." For "Old Command Type", select "Actor::module Usage Examples." "Command To Copy" should be "Custom Module Service.pm..." For "New Command Type" select the type we just created--"Sys Admin--Basic." Press "Copy" to create our new command. Now lets edit it. Return to the main window and press "Edit Commands." Select/Enter

Command Type: Sys Admin--Basic
Existing Commands: Custom Module Service.pm...
Display Name: Is The Service Running?

Note the value in "Perl Module"--"Actor::Service." This is the Actor::module that gets run after the user makes a request.

First press "Update" to save changes then "Edit Arguments." Now set HOST and VERB arguments to be "Hidden." Select the argument in "Existing Arguments." Select the "Hidden" radio button and press "Update." Make sure to press "Update" for each argument.

Now "Edit Arg Values." Select SERVICE from "Arguments" and edit the "Value" list--the list displayed as "Existing Values". Your users will see the "Display Name" instead of the value. Using httpd as an example, set the display name to "Apache Web Server."

Recall that we are only allowing "Basic" Sys Admin. Since we set VERB to be hidden, our user cannot choose from multiple argument values. Select VERB from "Arguments" and delete "start" and "stop" from "Existing Values" leaving only "status."

Finally we need to return to the main window --press the escape key three times--and "Assign Command Types To Users." Press the button and assign "Sys Admin--Basic" to "default_user."

Now lets check out Producer--the web application. Recall that the URL is something like this:
http://myactorserver:8080/producer_0.3.2

Click "Enter As Default User" on the login page and you will see our "Sys Admin--Basic" request type. If you see other request types make sure you are "default_user". Click the "Switch User" link if needed. Use the link under "Create a Request" to select a service and view status. The home page will refresh every thirty seconds or you can use use the refresh button to see when your request has finished running. Use the "log" link to view the output messages from the request.

Continuous Integration tools often use Ant (ant.apache.org) to build a software project whenever its source code changes. On the Actor home page click on "Switch To Continuous-Integration" then "Create A Request" as usual. This creates a request suitable for running from Ant. Actor provides an "Ant Task" to run these requests instead of running them on demand. Take a look at this sample ant build file: build.xml
See the actor-ant-task-demo target near the end of build.xml.

An important feature of Actor is the ability to run commands on remote servers. The current version of Actor uses SSH to connect to a remote Linux/Unix server and run the script. Contact the Author if you are interested in a Windows solution using XML-RPC. In addition to the ssh key setup, actor needs to setup the sudoers file.

# First copy consumer_0.3.2/setup/sudo4actor.pl
# from the actor distribution to
# /root/bin on the remote server. You will
# have your own strategy for accessing the
# remote server and putting a new file on it.
# So commands are not provided here.

# AS root ON THE REMOTE SERVER
useradd actor
passwd actor
su - actor
ssh-keygen -t rsa
exit
chmod +x /root/bin/sudo4actor.pl
/root/bin/sudo4actor.pl

vim /etc/ssh/sshd_config

# Edit sshd_config to contain the following setting:
StrictModes no

# For security purposes I suggest you disable
# login as root:
PermitRootLogin no

# Now restart sshd with the new settings.
service sshd restart

# AS root ON THE ACTOR SERVER
#
# To generate the key pair, run the following command
# and hit enter at all prompts. Do this only once
# on the Actor server. The keys will be put in
# /root/.ssh, if this directory already exists with
# the appropriate files, you do not need to run the
# command again.
ssh-keygen -t rsa
cat /root/.ssh/id_rsa.pub | \
ssh actor@remote_server 'cat >> .ssh/authorized_keys'

# Repeat the command below as needed. When it requires
# no additional user input we are done.
ssh actor@remote_server hostname

The best way to figure out Actor is to run Agent--the GUI setup application--and browse the existing examples. Pay particular attention to the commands under "Actor::module Usage Examples." New commands are easily setup by copying examples and editing them as we did in the tutorial.

After a user makes a request, Actor loads the Perl Module you setup and runs its "execute" method. To create new Actor::modules simply copy one of the existing .pm files in consumer/usr/Actor, change the package name and put your Perl code into the execute method. To run existing scripts and simple commands Actor's standard modules include Actor::RunLine and Actor::RunPositional. RunLine is particularly useful when you want to run a command on a remote server using ssh access. RunPositional is safe to use when an arg_value contains quotes, spaces or other problem characters.

My recommended trouble shooting process is to read the log files. Great pains have been taken to write meaningful messages to the logs when problems arise.

Producer uses Apache's Log4j for logging. By default the log messages go to standard output to be captured by the servlet container. For Tomcat that means $CATALINA_HOME/logs/catalina.out.

Producer's logging setup is found in producer/WEB-INF/classes/log4j.properties. If you have a global log4j.properties for Tomcat you may need to copy Producer's settings into it. Edit log4j.properties and you will see a number of "topics". If warning level log messages do not produce enough information set the levels to info or debug.

Consumer writes logs to /var/log/actor_yyyymmdd.log where yyyymmdd is the current date. Like Producer, the Consumer has a log4j.properties file --consumer/Actor/log4j.properties.

RUNNING CONSUMER DIRECTLY
To narrow down problems, stop the service --"service actor stop"--and run consumer directly. Run "consumer_0.3.2/actor.pl." In this case you will get log output directly on the console.

Take a look at the script used to run Agent--"cat bin/agent.sh." You will see the command line it uses with output sent to /dev/null. Leave off the pipe to /dev/null and run the rest of the command to see output on your console. Agent is a thin-client that connects to the web application through XML-RPC. So, it also helps to view logs for Producer when trouble shooting Agent.

Producer API Documentation
API documentaion for the Producer web application is available here.