Headless Client
Information
- The headless client is required for the implementation of batch jobs. I.e. for tasks to be performed on the 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 system 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)
- Windows: 32 bit version only
- The headless client is available in the
HeadlessClientsubdirectory in the installation directory of the PLANTA Server. The only thing to do is to unzip it in an appropriate path (e.g. Windows: C:\PLANTA\Jobs\Headless Or 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.
- Python version 2.6 or 2.7
- The PLANTA Server to which the headless client connects must be started and ready to take on client connections.
Details
- The
planta_headless.pyHeadless 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
0400octal 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 read and write permission.
- 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
--helpparameter (so e.g.python planta_headless.py --help), the usage information will be displayed. - By default, no output is generated since the cron daemon under Linux usually sends all console output via email to the responsible administrator. If an output for testing reasons is required, you can work with the
--verboseparameter, possibly combined with a file redirection. - The OS login mechanism has been extended on the 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.
Parameter
Options
| Parameter | Explanation |
|---|---|
| --version | Shows the version number and closes the program. |
| -h, --help | Shows the help message and closes the program. |
| -q, --quiet | Suppresses all output (preset) |
| -v, --verbose | The "verbosity level" is increased each time the parameter is set additionally (e.g. -v -v... or -vv) (maximum level 3). Info message..., XML sent..., etc. |
Connection Parameters
| Parameter | Explanation |
|---|---|
| -s HOST:PORT, --service=HOST:PORT | Connection to the server |
| -t TIMEOUT, --timeout=TIMEOUT | Waiting time until job completion in seconds -1 for no time-out |
Login Parameters
| Parameter | Explanation |
|---|---|
| -u USER_NAME, --user=USER_NAME | User name for logout to the PLANTA system |
| -a TYPE, --auth_type=TYPE | Authentication type used for login to the PLANTA system "osuser" or "challenge" |
| -p SECRET_FILE, --secret=SECRET_FILE | File which contains the password hash |
| -i INDIVIDUAL_PARAMETERS, --individual_parameters=INDIVIDUAL_PARAMETERS | Parameter for the launched session, arbitrary text, e.g.: "{para1:'value1',para2:'value2'}" |
Job Specifications
| Parameter | Explanation |
|---|---|
| -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 new Python file on the server. |
| -c PYTHON_CODE, --py_code=PYTHON_CODE | The job runs a Python code excerpt (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 implicate an error. The jobs are edited until they are terminated. However, the client disconnects before that. - 4: Authentication failed
- 5: Unexpected exception (currently within the autentication via the "challenge" type)
- 6: Login-Time-out: if login takes longer than 20 seconds
- 7: Server quits the session while a job is running
- 8: Internal server error
- 9: No open module could be found (required to run jobs)
Time-Out of the Headless Client
Note
- Depending on the time time out parameter and the 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 out is specified, the action is only initiated without waiting for the session to be terminated.
- Only with the help of the
--timeout=-1parameter 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.