Revision 3 as of 2009-12-15 10:46:52

Clear message

Running scripts

You can use Landscape to run scripts on the machines you manage in your account.

{i} Note: remotely executing scripts could be a security problem. That's why you must manually enable script execution on each machine you manage.

Using scripting in Landscape you can:

  • create a library of scripts you use regularly or simply paste and run scripts you'll only use once
  • choose which user should run the script on the remote machines
  • use any interpreter that's installed on the remote machines -- you can always remotely install a new interpreter using Landscape.

If you've already enabled script execution on your machines, you can get started straight away. Otherwise, follow the steps to allow script execution on individual computers.

Enabling script execution

When you installed the Landscape client on your remote machines, it asked you if you wanted to enable script execution. If you chose "no", it's easy to now enable script execution.

Step 1: Open a terminal on the computer or log in using SSH.

Step 2: Run the Landscape configuration tool:

 $ sudo landscape-config

Step 3: The configuration tool will ask you the same questions as when you ran it for the first time. Hitting Enter will select the answers you provided last time. Answer Y when it asks if you want to enable scripting:

(...)
Landscape has a feature which enables administrators to run
arbitrary scripts on machines under their control. By default this
feature is disabled in the client, disallowing any arbitrary script
execution. If enabled, the set of users that scripts may run as is
also configurable.

Enable script execution? [y/N]y

Step 4: When you use Landscape to run scripts on your machines, you have to choose which user (or users) they will be allowed to run as. If you want to allow Landscape to run scripts as any user, answer ALL. The example below shows how to enable script execution for the users "nobody" and "dsa" only:

By default, scripts are restricted to the 'landscape' and
'nobody' users. Please enter a comma-delimited list of users
that scripts will be restricted to. To allow scripts to be run
by any user, enter "ALL".

Script users: nobody,dsa

/!\ Very important: when using this method, you MUST NOT request a new registration for the computer, as that will create a duplicate machine in your Landscape account!

Alternative method

Add include_manager_plugins = ScriptExecution and script_users = <comma-separated-list-of-users> to the /etc/landscape/client.conf file on the computer and then restart the Landscape client. For example:

    include_manager_plugins = ScriptExecution
    script_users = nobody,dsa

You can also use "ALL" in the script_users line.

One-time scripts

There are two ways to run scripts using Landscape:

  • one-time scripts: paste your script into the text box, select your options and go

  • stored scripts: build a library of scripts that you want to use more than once.

Let's try a one-time script. As with most things you do in Landscape, running a script starts with a visit to the Computers page of your account. Select the machines you want to work with, then click the Scripts icon in the toolbar at the bottom of the page.

Landscape will show you the script form. Let's take a look at each field in turn:

Title: this can be anything you choose and is a simple identifier to help you recognize this script in the activities list later on. Here, we'll enter List connected users.

Interpreter: in most cases you'll probably use a shell, such as /bin/bash or /bin/zsh, but it can also be a more complex interpreter such as /usr/bin/python or /usr/bin/perl. So long as the interpreter is installed on the remote machine, you can use it to run your script. We'll use the default value of /bin/bash for our test.

Code: this is the meat of your script and is what Landscape passes to the interpreter you specified above. We'll put w -fhs here.

Time limit: the time in seconds that we want to give the script to finish executing on the remote machines. The default value, 300 seconds, will fit most uses, but you may want to allow for more or less time depending on what your script does.

Run as user: the drop-down list allows you to select the user the scripts will be run as. In our case, the default user nobody is a good choice.

{i} Note: Landscape will present you only with those users that are available on every machine.

We'll cover attachments later, so for now let's press Run.

{i} Note: If you click on Save and Run, the script will also be stored in the script library which is covered later in this document.

Viewing your script's output

While Landscape is busy asking your selected computers to run the script, it'll keep you updated using the activity page. Please reload it periodically to watch its progress.

After a few minutes, you should see a Succeeded header for each computer along with an icon showing that the script's output is available. Clicking one of those activities will show you the result of the script on the selected machine. In our case, it's the output of w -fhs.

No user available

When you first register a computer, it can take a few hours before Landscape has all the information it needs about the machine. The user information part, however, is usually much faster and should only take a few minutes.

If you try to run a script on a machine for which Landscape doesn't have the user list yet, you will this error:

There is no set of common users on the selected computers. A set of common users must be available before script execution can be used.

That means that Landscape doesn't yet know which users are available on the remote machine. Wait a while and then try again. You can check if the user list is available by going to the Users icon in the bottom toolbar.

Stored scripts

If you expect to run a script more than once, you can save time by storing it in your script library.

Click Stored scripts in the left-hand menu, then the Add button at the bottom-right of the page.

You'll recognize the form that Landscape gives you: it's almost the same as the one we used earlier, the only noticeable difference being that you don't need to specify a user. In place of the drop-down list of users we saw on the other form, you now have an optional text-field. If you leave the field blank, you will have to specify the user each time you run the script later on.

Fill out the other values as you did previously and then click Save. Landscape will then redirect you to your Stored scripts page where you can select and remove scripts.

For now, let's run the newly stored script! Click Computers in the left-hand menu, select the computers where you want to run the script on and then click Scripts in the bottom menu.

Unlike last time, you'll now have the option to run a new script or select the one you've just stored.

Select the stored script then click Next.

There, you see your form filled with the values you specified in the stored script. If you want to customize the script for this run, you can alter each field.

{i} Note: any changes you make here apply only to this run and will not be saved in your script library.

Unknown user

If you specified a user when you created your stored script, and that user is not available on all selected machines when you try to run it, you'll get the following warning:

The default user for this script, $USER, is not available on all selected computers. Please select a user that is present on all selected computers..

Simply select another user and then run the script as normal.

Attachments

If you want to use additional files with your script -- configuration files, other scripts, pictures and so on -- you can add them as attachments.

Each script can have up to five attachments, totalling no more than 1 MB: for example, one 1 MB file or five 200 KB files. Attachments are available for both one-shot scripts and stored scripts.

Let's use them in an example where we change the desktop background of a user.

Select the computers you want to work with, as before, then click Scripts. Leave Run a new script selected, then click Next.

Enter Change background as the title, leave /bin/bash as the interpreter and add the following code:

cp $LANDSCAPE_ATTACHMENTS/back.png $HOME/
gconftool-2 --type string --set /desktop/gnome/background/picture_filename $HOME/back.png

LANDSCAPE_ATTACHMENTS is an environment variable set by the Landscape client and represents a directory where all the attachments are placed before the script runs. If you are using Python, the value would be accessible using os.getenv("LANDSCAPE_ATTACHMENTS"), for example.

In our case, we copy the picture to the home directory of the user and then call gconftool to change the desktop background. Note that this works only for the default Ubuntu desktop (Gnome).

Use the drop-down list to select the user whose background you want to change, then attach a picture named back.png, or whatever file name you chose in your script. Just remember it has to be the same name as used in the script.

Click Run and your browser will upload the attachment to the Landscape server and then send it with the script to the selected computers.

Forgetting to use LANDSCAPE_ATTACHMENTS

If you attach a file to a script but don't use the variable LANDSCAPE_ATTACHMENTS anywhere in your script code, it's likely that you've made a mistake.

Landscape looks out for that sort of error and will warn you if you've omitted the variable but have uploaded attachments.

Example Scripts

There are some example scripts here.