Headless Client

Information

• The headless client is required for the implementation of batch jobs. I.e. for tasks to be performed on part of the server without user interaction, that are initiated by a scheduler (Task Manager in Windows or cron in Linux) on a regular basis.
• For the creation of the headless client, profound knowledge of the corresponding administrative subject areas is required.

Requirements

• The following must be installed on the computer on which the headless client is installed and started (typically the application server but it may be any random client as well):
  • Python version 2.6 or 2.7.
    • Windows: 32 bit version only
      • Free download: http://python.org/ftp/python/2.7.3/python-2.7.3.msi
    • Linux: 64 or 32 bit version
      • Available in all common current distribution repositories (otherwise: http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz)
  • The Headless Client packet is available in zipped form in the release packet (though it is not contained in every packet, the last version is contained in Current Releases 39.4.x. 4.4.0). The only thing to do is to unzip it in an appropriate path (e.g. Windows: C:\PLANTA\Jobs\Headless / Linux: /planta/jobs/headless)
    • The available Headless Client packet is platform-independent and can be used for Windows as well as for Linux.
  • For the Headless Client, a standard client is required on the respective system.

Details

• The planta_headless.py Headless Client Python start script receives all parameters via the command line, except the password, which is read from a file, due to security reasons.
  • This file contains the bcrypt-encrypted hash of the PLANTA user's password and should only be readable for the user who is authorized to start jobs with this PLANTA user.
  • Creating this password file in the appropriately protected headless directory and using the 0400 octal access rights should be sufficient in order to guarantee a certain degree of security, even though all other access controls, available for the administrator, are supported.
  • First, the file is created upon opening the headless client by specifying a file that's not available in a path for which the user has reading and editing rights.
  • In this case, the headless client will ask for the password and save the corresponding hash with the given name in a newly created password file.
• By opening the headless client with the --help parameter (so e.g. python planta_headless.py --help), the usage information is displayed.
• By default, no output is generated since the cron daemon usually sends all console output via e-mail to the responsible administrator. If an output for testing reasons is required, you can work with the --verbose parameter, possibly combined with a file redirection.
• The OS login mechanism was extended on part of the server, visible also in the headless client.
  • However, the adjustment of the headless client only serves the downward compatibility for users who don't use the extended OS login.
  • The challenge response authentification is particularly recommended for those who have enhanced security requirements for the system access.
• All parameters with short explanation:

# planta_headless.py --version
planta_headless.py 39 Mars

# planta_headless.py --help
Usage: planta_headless.py [options]

Options:
  --version             Shows the version number and closes the program
  -h, --help            Shows this help message and closes the program
  -q, --quiet           Suppresses all output (default)
  -v, --verbose         Increases the verbosity level with each event: Info-
                        Message, XML sent, XML received
  Connection settings:
    -s HOST:PORT, --service=HOST:PORT
                        Connection to server
    -t TIMEOUT, --timeout=TIMEOUT 
                        Waiting time until job termination in seconds, -1 for
                        no time out

  Login options:
    -u USER_NAME, --user=USER_NAME
                        User name for the PLANTA system login
    -a TYPE, --auth_type=TYPE
                        used authentification type for PLANTA login-
                        System: "osuser" or "challenge"
    -p SECRET_FILE, --secret=SECRET_FILE
                        File containing the password hash

  Job specifications:
    -m MOD_ID, --module=MOD_ID
                        The job opens the module with the specified ID on the server.
    -f PYTHON_FILE, --py_file=PYTHON_FILE
                        The job runs a python file
                        on the server.
    -c PYTHON_CODE, --py_code=PYTHON_CODE
                        The job runs a Python code snippet 
                        on the server.

Return Codes

Values

• 0: Ok, jobs were terminated successfully
• 1: Socket or connection error
• 2: Parameter error
• 3: Time out, while the server was editing jobs (This does not necessarily indicate an error. The jobs are edited until they are terminated. However, the client disconnects before that.)

Timeout of the Headless Clients

Notes

• Depending on the time out parameter and action running time, the headless client quits itself directly after action start, according to a firmly defined time frame or after termination of the action.
• If no time out is specified, the action is only initiated without waiting for the session to be terminated.
• Only with the help of the --timeout=-1 parameter, you can make sure that the headless client runs for the exact same time as the session.
• It is essential that you specify this parameter in order to make sure that a batch job can only run once at a time, as it is for the Windows Task Scheduler.