Command-Line Tools¶
The CLI tools are installed with the bluesky-queueserver package:
start-re-manager - start RE Manager.
qserver - communicate with RE Manager over 0MQ.
qserver-list-plans-devices - generate list of existing plans and devices, validate startup code.
qserver-zmq-keys - generate key pair for encryption of 0MQ control channel.
qserver-console-monitor - simple monitor of RE Manager console output.
qserver-clear-lock - unlock RE Manager if the lock key is lost.
start-re-manager¶
The command starts Run Engine (RE) Manager on the workstation. If no parameters are specified, RE Manager is started in demo mode (built-in startup files with simulated devices and plans will be used). Demo mode is intended for evaluation and testing of Queue Server. The CLI parameters may be used to customize RE Manager and specify the location of beamline startup scripts.
Using a Configuration Files¶
RM Manager can be customized using a config file (YML). Combining the parameters
in a single config file may be more convenient in production deployments. The path
to config file is passed to the manager using environment variable QSERVER_CONFIG
or using CLI parameter --config
. CLI parameters passed to start-re-manager
override the parameters set in config file or passed using environment variables.
Location of Startup Code¶
RE Manager may create RE Worker environments based based on startup code from
IPython-style collection of startup scripts, Python script or Python module.
The locations of autogenerated existing_plans_and_devices.yaml
file (see
Updating the List of Existing Plans and Devices and
qserver-list-plans-devices) and user_group_permissions.yaml
must also be specified. The existing_plans_and_devices.yaml
file is
optional and could be generated automatically by opening RE Worker environment,
but the path to the file pointing to a location in existing directory must be
properly specified. Alternatively, the file can be initially generated by
qserver_list_plans_devices
CLI tool.
IPython-style collection of startup scripts:
Use the parameter --startup-dir
to specify the directory path to
the collection of startup file. Both .yaml
files are expected to be
located in the startup directory. If the location the .yaml
files is different,
use the parameters --existing-plans-devices
and --user-group-permissions
to specify the correct paths.
Ipython profile:
If the collection of startup scripts is located in startup
directory in
one of the IPython profiles, the profile name may be passed to RE Manager
using the parameter --startup-profile
. This option is implemented for
convenience and allows to avoid specifying long path to startup directory.
Python script:
Use the parameter --startup-script
to specify the path to Python
script that contains startup code (.py
file). Only the single script
will be loaded. The script may contain imports from other scripts or modules.
Since there is no obvious location for the .yaml
files, the paths
to the files must be explicitely specified using parameters
--existing-plans-devices
and --user-group-permissions
.
Python module:
Use the parameter --startup-module
to specify the name of the installed
module that contains startup code. Paths to both .yaml
files must be
explicitly specified.
Instances of Run Engine and Databroker¶
By default, RE Manager removes RE
and db
objects from RE Worker
namespace and creates the new instances. In many cases, startup scripts contain
the code that creates and configures instances RE
and/or db
.
To disable the default behavior and keep instances of RE
and db
created in startup scripts, start RE Manager with the parameter --keep-re
.
RE Worker environment will fail to open if --keep-re
is used and startup
scripts do not create the instance of RE
.
RE Manager supports a number of standard options of subscribing RE
to callbacks.
All the subscriptions can be performed in startup code, so those options
are implemented mostly for convenience. The options work in cases when
RE
is created in startup script or RE Manager. (Note, that --keep-re
must be used to preserve the instance of RE
created in the startup script.
The parameters supporting the subscription options:
--databroker-config
subscribes RE to Data Broker with the given configuration name.--zmq-data-proxy-addr
address of 0MQ proxy for publishing documents generated by Run Engine.--kafka-server
and--kafka-topic
for publishing documents generated by Run Engine.--use-persistent-metadata
enables msgpack-based persistent storage for scan metadata
Updating the List of Existing Plans and Devices¶
The --update-existing-plans-devices
parameter determines when the lists of existing plans
and devices stored in a disk file is updated by Queue Server. See notes on the location of
the file with the lists of existing plans and devices in Using a Configuration Files.
The lists are loaded from the disk file by RE Manager process at startup and used to generate
the initial lists of allowed plans and devices. Those lists are used for validation of
submitted plans, allowing user to submit plans to the queue before startup scripts are
loaded. The lists are also distributed to clients and used for generating user interfaces.
Therefore, it is important to keep the stored lists of existing plans and devices up to date.
The parameter allows to select between the following modes for updating the lists:
NEVER
- Queue Server never overwrites the existing file or create a new file if it is missing. Users need to update the file by manually runningqserver-list-plans-devices
CLI tool. Opening the RE Worker environment generates the lists of existing plans and devices that could be used during the current session, but it will not be saved to the file. The next time Queue Server is started, the original lists of existing plans and devices is loaded from disk. ‘permissions_reload’ 0MQ API called with parameterrestore_plans_devices=True
will also reload the original list from disk. Restarting the RE Manager process while the environment is open will not read the list of existing plans and devices from disk. This option may be used in workflows with ‘static’, rarely changed startup scripts where it is preferred that the lists of existing plans and devices is not dynamically changed.ENVIRONMENT_OPEN
(default) - Queue Server verifies if the lists of existing plans and devices are out of date each time RE Worker environment is opened and saves the new lists to the file when necessary. This ensures that the next time Queue Server is started, the latest up-to-date version of the lists is loaded. In this mode, it is not necessary to call useqserver-list-plans-devices
to generate the lists. Instead it could be left to Queue Server to update the stored lists. Note, that Queue Server will not know about changes to startup code until the operation of opening RE Worker environment is successfully completed.qserver-list-plans-devices
may still be useful for debugging the startup code or generating lists of existing plans and devices in cases when starting Queue Server is inconvenient.ALWAYS
- Queue Server updates the lists of existing plans and devices stored in file each time plans and devices are added to or removed from to RE namespace. This is option is not fully utilized yet and results in behavior identical toENVIRONMENT_OPEN
.
Console Ouput¶
RE Manager captures output to stdout
and stderr
produced by itself and
running plans. The output may be printed to terminal and/or published to
a 0MQ socket (different socket from the socket used for control communication).
--zmq-info-addr
allows to set the address for the 0MQ ‘PUB’ socket.Setting
--zmq-publish-console ON
enables publishing of the collected output to 0MQ socket.Setting
--console-output OFF
disables printing to terminal.
Encryption for 0MQ Control Communication Channel¶
If the QSERVER_ZMQ_PRIVATE_KEY_FOR_SERVER
environment variable contains a string
that represents valid private key, the enryption for control channel is enabled.
Clients must use correct public key from public/private key pair to communicate with
RE Manager. Public/private key pair can be generated using qserver-zmq-keys.
Other Configuration Parameters¶
--zmq-control-addr
is the address of 0MQ socket for the server. The server is managed by RE Manager and used to pass control commands from clients.--redis-addr
is the address of Redis server used by RE Manager as persistent storage.--verbose
,--quiet
and--silent
options modify logging verbosity level for RE Manager.
start-re-manager -h
displays help information:
$ start-re-manager -h
usage: start-re-manager [-h] [--config CONFIG_PATH] [--zmq-control-addr ZMQ_CONTROL_ADDR]
[--zmq-addr ZMQ_ADDR]
[--startup-dir STARTUP_DIR | --startup-profile PROFILE_NAME |
--startup-module STARTUP_MODULE_NAME | --startup-script STARTUP_SCRIPT_PATH]
[--existing-plans-devices EXISTING_PLANS_AND_DEVICES_PATH]
[--update-existing-plans-devices {NEVER,ENVIRONMENT_OPEN,ALWAYS}]
[--user-group-permissions USER_GROUP_PERMISSIONS_PATH]
[--user-group-permissions-reload {NEVER,ON_REQUEST,ON_STARTUP}]
[--redis-addr REDIS_ADDR] [--kafka-topic KAFKA_TOPIC]
[--kafka-server KAFKA_SERVER]
[--zmq-data-proxy-addr ZMQ_DATA_PROXY_ADDR] [--keep-re]
[--use-persistent-metadata]
[--databroker-config DATABROKER_CONFIG]
[--zmq-info-addr ZMQ_INFO_ADDR]
[--zmq-publish-console-addr ZMQ_PUBLISH_CONSOLE_ADDR]
[--zmq-publish-console {ON,OFF}] [--console-output {ON,OFF}]
[--verbose | --quiet | --silent]
Start Run Engine (RE) Manager
bluesky-queueserver version 0.0.17.post32.dev0+ga4ba9d1
Encryption for ZeroMQ communication server may be enabled by setting the value of
'QSERVER_ZMQ_PRIVATE_KEY_FOR_SERVER' environment variable to a valid private key
(z85-encoded 40 character string):
export QSERVER_ZMQ_PRIVATE_KEY_FOR_SERVER='<private_key>'
A public/private key pair may be generated by running 'qserver-zmq-keys'. If RE Manager is
configured to use encrypted channel, the encryption must also be enabled at the client side
using the public key from the generated pair. Encryption is disabled by default.
optional arguments:
-h, --help show this help message and exit
--config CONFIG_PATH
Path to a YML config file or a directory containing multiple config
files. The path passed as a parameter overrides the path set using
QSERVER_CONFIG environment variable. The config path must point to an
existing file or directory (may be empty), otherwise the manager can
not be started.
--zmq-control-addr ZMQ_CONTROL_ADDR
The address of ZMQ server (control connection). The parameter
overrides the address defined by the environment variable
QSERVER_ZMQ_CONTROL_ADDRESS_FOR_SERVER. The default address is used if
the parameter or the environment variable is not defined. Address
format: 'tcp://*:60615' (default: 'tcp://*:60615').
--zmq-addr ZMQ_ADDR
The parameter is deprecated and will be removed in future releases.
Use --zmq-control-addr instead.
--startup-dir STARTUP_DIR
Path to directory that contains a set of startup files (*.py and
*.ipy). All the scripts in the directory will be sorted in
alphabetical order of their names and loaded in the Run Engine Worker
environment. The set of startup files may be located in any accessible
directory.
--startup-profile PROFILE_NAME
The name of IPython profile used to find the location of startup
files. Example: if IPython is configured to look for profiles in
'~/.ipython' directory (default behavior) and the profile name is
'testing', then RE Manager will look for startup files in
'~/.ipython/profile_testing/startup' directory.
--startup-module STARTUP_MODULE_NAME
The name of the module with startup code. The module is imported each
time the RE Worker environment is opened. Example:
'some.startup.module'. Paths to the list of existing plans and devices
(--existing-plans-and-devices) and user group permissions (--user-
group-permissions) must be explicitly specified if this option is
used.
--startup-script STARTUP_SCRIPT_PATH
The path to the script with startup code. The script is loaded each
time the RE Worker environment is opened. Example:
'~/startup/scripts/scripts.py'. Paths to the list of existing plans
and devices (--existing-plans-and-devices) and user group permissions
(--user-group-permissions) must be explicitly specified if this option
is used.
--existing-plans-devices EXISTING_PLANS_AND_DEVICES_PATH
Path to file that contains the list of existing plans and devices. The
path may be a relative path to the profile collection directory. If
the path is directory, then the default file name
'existing_plans_and_devices.yaml' is used.
--update-existing-plans-devices {NEVER,ENVIRONMENT_OPEN,ALWAYS}
Select when the list of existing plans and devices stored on disk
should be updated. The available choices are not to update the stored
lists (NEVER), update the lists when the environment is opened
(ENVIRONMENT_OPEN) or update the lists each the lists are changed
(ALWAYS) (default: ENVIRONMENT_OPEN)
--user-group-permissions USER_GROUP_PERMISSIONS_PATH
Path to file that contains lists of plans and devices available to
users. The path may be a relative path to the profile collection
directory. If the path is a directory, then the default file name
'user_group_permissions.yaml' is used.
--user-group-permissions-reload {NEVER,ON_REQUEST,ON_STARTUP}
Select when user group permissions are reloaded from disk. Options:
'NEVER' - RE Manager never attempts to load permissions from disk
file. If permissions fail to load from Redis, they are loaded from
disk at the first startup of RE Manager or on request. 'ON_REQUEST' -
permissions are loaded from disk file when requested by
'permission_reload' API call. 'ON_STARTUP' - permissions are loaded
from disk each time RE Manager is started or when 'permission_reload'
API request is received (default: ON_STARTUP)
--redis-addr REDIS_ADDR
The address of Redis server, e.g. 'localhost', '127.0.0.1',
'localhost:6379' (default: localhost).
--kafka-topic KAFKA_TOPIC
The kafka topic to publish to.
--kafka-server KAFKA_SERVER
Bootstrap server to connect (default: 127.0.0.1:9092).
--zmq-data-proxy-addr ZMQ_DATA_PROXY_ADDR
The address of ZMQ proxy used to publish data. If the parameter is
specified, RE is subscribed to 'bluesky.callbacks.zmq.Publisher' and
documents are published via 0MQ proxy. 0MQ Proxy (see Bluesky 0MQ
documentation) should be started before plans are executed. The
address should be in the form '127.0.0.1:5567' or 'localhost:5567'.
The address is passed to 'bluesky.callbacks.zmq.Publisher'. It is
recommended to use Kafka instead of 0MQ proxy in production data
acquisition systems and use Kafka instead.
--keep-re Keep RE created in profile collection. If the flag is set, RE must be
created in the profile collection for the plans to run. RE will also
keep all its subscriptions. Also must be subscribed to the Data Broker
inside the profile collection, since '--databroker-config' argument is
ignored.
--use-persistent-metadata
Use msgpack-based persistent storage for scan metadata. Currently this
is the preferred method to keep continuously incremented sequence of
Run IDs between restarts of RE.
--databroker-config DATABROKER_CONFIG
Name of the Data Broker configuration file.
Configure console output:
The arguments allow to configure printing and publishing of the console output
generated by RE Manager. The arguments allow to set the address of 0MQ socket
and enable/disable printing and/or publishing of the console output.
--zmq-info-addr ZMQ_INFO_ADDR
The address of ZMQ server socket used for publishing information on
the state of RE Manager and currently running processes. Currently
only the captured STDOUT and STDERR published in 'QS_Console' topic.
The parameter overrides the address defined by the environment
variable 'QSERVER_ZMQ_INFO_ADDRESS_FOR_SERVER'. The default address is
used if the parameter or the environment variable is not defined.
Address format: 'tcp://*:60625' (default: tcp://*:60625).
--zmq-publish-console-addr ZMQ_PUBLISH_CONSOLE_ADDR
The parameter is deprecated and will be removed in future releases.
Use --zmq-info-addr instead.
--zmq-publish-console {ON,OFF}
Enable (ON) or disable (OFF) publishing of console output to 0MQ
(default: OFF).
--console-output {ON,OFF}
Enable (ON) or disable (OFF) printing of console output in the Re
Manager terminal. (default: ON)
Logging verbosity settings:
The default logging settings (loglevel=INFO) provide optimal amount of data to monitor
the operation of RE Manager. Select '--verbose' option to see detailed data on received and
sent messages, added and executed plans, etc. Use options '--quiet' and '--silent'
to see only warnings and error messages or disable logging output.
--verbose Set logger level to DEBUG.
--quiet Set logger level to WARNING.
--silent Disables logging output.
qserver¶
qserver
CLI tool allows to communicate with the server by typing commands in command
line. The tool is primarily intended for testing or diagnostics of Queue Server and emergency use
in production. The tool supports most of the Queue Server 0MQ API including submitting plans,
opening and closing of RE Worker environment, starting and stopping the queue, etc.
Refer to qserver
help for the full list of supported commands.
If RE Manager 0MQ address is different from the default, use the optional --zmq-control-addr
parameter or QSERVER_ZMQ_CONTROL_ADDRESS
to pass the address to qserver
. If encryption
is enabled at RE Manager, set the environment variable QSERVER_ZMQ_PUBLIC_KEY
to a string
representing valid public address of the 0MQ server. Use qserver-zmq-keys tool
to generate a new public/private key pair or generate public key from known server private key.
qserver may used in monitoring mode (qserver monitor
). In this mode the tool
periodically requests and displays the status of Queue Server.
qserver -h
displays help information:
$ qserver -h
usage: qserver [-h] [--zmq-control-addr ZMQ_CONTROL_ADDR] [--address ADDRESS]
command [command ...]
Command-line tool for communicating with RE Monitor.
bluesky-queueserver version 0.0.16
positional arguments:
command a sequence of keywords and parameters that define the command
optional arguments:
-h, --help show this help message and exit
--zmq-control-addr ZMQ_CONTROL_ADDR, -a ZMQ_CONTROL_ADDR
Address of the control socket of RE Manager. The parameter overrides
the address set using the environment variable
QSERVER_ZMQ_CONTROL_ADDRESS. The default value is used if the address
is not set using the parameter or the environment variable. Address
format: 'tcp://127.0.0.1:60615' (default: 'tcp://localhost:60615').
--address ADDRESS
The parameter is deprecated and will be removed. Use --zmq-control-
addr instead.
If RE Manager is configured to use encrypted ZeroMQ communication channel,
the encryption must also be enabled before running 'qserver' CLI tool by setting
the environment variable QSERVER_ZMQ_PUBLIC_KEY to the value of a valid public key
(z85-encoded 40 character string):
export QSERVER_ZMQ_PUBLIC_KEY='<public_key>'
Encryption is disabled by default.
Examples of CLI commands
------------------------
qserver -h # Display help
qserver monitor # Start 'qserver' in monitoring mode
qserver ping # Send 'ping' request to RE Manager via ZMQ
qserver status # Request status of RE Manager
qserver environment open # Open RE environment
qserver environment close # Close RE environment
qserver environment destroy # Destroy RE environment (kill RE worker process)
qserver existing plans # Request the list of existing plans
qserver existing devices # Request the list of existing devices
qserver allowed plans # Request the list of allowed plans
qserver allowed devices # Request the list of allowed devices
qserver permissions reload # Reload user permissions and generate lists of allowed plans and devices.
qserver permissions reload lists # Same, but reload lists of existing plans and devices from disk.
qserver permissions set <path-to-file> # Set user group permissions (from .yaml file)
qserver permissions get # Get current user group permissions
qserver queue add plan '<plan-params>' # Add plan to the back of the queue
qserver queue add instruction <instruction> # Add instruction to the back of the queue
qserver queue add plan front '<plan-params>' # Add plan to the front of the queue
qserver queue add plan back '<plan-params>' # Add plan to the back of the queue
qserver queue add plan 2 '<plan-params>' # Insert plan at position 2
qserver queue add instruction 2 <instruction> # Insert instruction at position 2
qserver queue add plan -1 '<plan-params>' # Insert plan at position -1
qserver queue add plan before '<uid>' '<plan-params>' # Insert the plan before the plan with given UID
qserver queue add plan after '<uid>' '<plan-params>' # Insert the plan after the plan with given UID
NOTE: Position indices are 0-based. Inserting a plan to position 0 pushes it to the front of the queue.
Negative position indices are counted from the back of the queue. Request for a plan with index -1
returns the last plan of the queue. Inserting a plan at position -1 makes it previous to last.
qserver queue update plan <uid> '<plan-params>' # Update item with <uid> with a plan
qserver queue replace plan <uid> '<plan-params>' # Replace item with <uid> with a plan
qserver queue update instruction <uid> '<instruction>' # Update item with <uid> with an instruction
qserver queue replace instruction <uid> '<instruction>' # Replace item with <uid> with an instruction
qserver queue execute plan '<plan-params>' # Immediately execute the plan
qserver queue execute instruction <instruction> # Immediately execute an instruction
Example of JSON specification of a plan:
'{"name": "count", "args": [["det1", "det2"]], "kwargs": {"num": 10, "delay": 1}}'
Supported queue instructions:
queue-stop # stops execution of the queue
qserver queue get # Request the list of items (plans or instructions) in the queue
qserver queue clear # Clear the queue (remove all plans from the queue)
qserver queue item get # Request the last item in the queue
qserver queue item get back # Request the last item in the queue
qserver queue item get front # Request the first item in the queue
qserver queue item get 2 # Request the item at position 2
qserver queue item get '<uid>' # Request the item with given Item UID
qserver queue item remove # Remove the last item from the queue
qserver queue item remove back # Remove the last item from the queue
qserver queue item remove front # Remove the first item from the queue
qserver queue item remove 2 # Remove the item at position 2
qserver queue item remove '<uid>' # Remove the item with the given UID
qserver queue item move 2 5 # Move item from position 2 to position 5 of the queue
qserver queue item move back front # Move item from the back to the front of the queue
qserver queue item move front -2 # Move item from the front of the queue to position -2
qserver queue item move '<uid-src>' 5 # Move item with UID <uid-src> to position 5
qserver queue item move 2 before '<uid-dest>' # Place item at position 2 before an item with <uid-dest>
qserver queue item move 2 after '<uid-dest>' # Place item at position 2 after an item with <uid-dest>
qserver queue item move '<uid-src>' before '<uid-dest>' # Place item with <uid-src> before item with <uid-dest>
qserver queue start # Start execution of the queue
qserver queue stop # Request execition of the queue to stop after current plan
qserver queue stop cancel # Cancel request to stop execution of the queue
# Queue can operate in LOOP mode, which is disabled by default. To enable or disable the LOOP mode use
qserver queue mode set loop True
qserver queue mode set loop False
# The following requests are forwarded to the Run Engine:
qserver re pause # Request to PAUSE currently executed plan at the next checkpoint
qserver re pause deferred # Request to PAUSE currently executed plan at the next checkpoint
qserver re pause immediate # Request to immediately PAUSE currently executed plan
qserver re resume # RESUME execution of a paused plan
qserver re stop # STOP execution of a paused plan
qserver re abort # ABORT execution of a paused plan
qserver re halt # HALT execution of a paused plan
qserver re runs # Get the list of active runs (runs generated by the currently running plans)
qserver re runs active # Get the list of active runs
qserver re runs open # Get the list of open runs (subset of active runs)
qserver re runs closed # Get the list of closed runs (subset of active runs)
qserver history get # Request plan history
qserver history clear # Clear plan history
qserver function execute <function-params> # Start execution of a function
qserver function execute <function-params> background # ... in the background thread
Example of JSON specification of a function ("args" and "kwargs" are optional):
'{"name": "function_sleep", "args": [20], "kwargs": {}}'
qserver script upload <path-to-file> # Upload a script to RE Worker environment
qserver script upload <path-to-file> background # ... in the background
qserver script upload <path-to-file> update-re # ... allow 'RE' and 'db' to be updated
qserver task result <task-uid> # Load status or result of a task with the given UID
qserver task status <task-uid> # Check status of a task with the given UID
qserver lock environment -k 90g94 # Lock the environment
qserver lock environment "Locked for 1 hr" -k 90g94 # Add a text note
qserver lock queue -k 90g94 # Lock the queue
qserver lock all -k 90g94 # Lock environment and the queue
qserver lock info # Load lock status
qserver lock info -k 90g94 # Load lock status and validate the key
qserver unlock -k 90g94 # Unlock RE Manager
qserver manager stop # Safely exit RE Manager application
qserver manager stop safe on # Safely exit RE Manager application
qserver manager stop safe off # Force RE Manager application to stop
NOTE: Exit with 'safe on' option will succeed only if RE Manager is in IDLE state (queue is not running).
If called with 'safe off' option, the request will force RE Manager to terminate RE Worker process and
exit even if a plan is running.
qserver manager kill test # Kills RE Manager by stopping asyncio event loop. Used only for testing.
qserver-list-plans-devices¶
qserver-list-plans-devices
loads the startup code and generates the lists of existing plans and devices.
The tool may be used for the following purposes:
Validation of startup code. If startup code is successfully loaded by
qserver-list-plans-devices
it is very likely that it will be successfully loaded into the RE Worker environment.Generation of the list of existing plans and devices (
existing_plans_and_devices.yaml
). Queue Server may be configured to automatically generate or update the file (see Updating the List of Existing Plans and Devices), but sometimes it may be more convenient to do it manually or as part of the installation script.
The lists of existing plans and devices must be updated each time new devices or plans are added to or removed from the startup code or signatures of the existing plans are modified (e.g. a parameter is added or removed, type annotation or text description is changed etc.), since those changes may affect other functionality such as plan validation or lists of allowed plans and devices distributed to clients.
The default name for the output file is existing_plans_and_devices.yaml
. The file is always
saved to the current directory unless a different path is specified using the --file-dir
parameter. If the output file must have name different from the default, the new name
can be specified using the --file-name
parameter.
The tool may load startup code from IPython startup script collection, Python script or Python module.
Use --startup-dir
, --startup-script
and --startup-module
parameters to specify
the path to the directory with startup files, the path to a startup script or module name respectively.
qserver-list-plans-devices -h
displays help information:
$ qserver-list-plans-devices -h
usage: qserver-list-plans-devices [-h] [--file-dir FILE_DIR] [--file-name FILE_NAME]
[--startup-dir STARTUP_DIR | --startup-module STARTUP_MODULE_NAME | --startup-script STARTUP_SCRIPT_PATH]
Bluesky-QServer:
CLI tool for generating the list of plans and devices from beamline startup scripts.
bluesky-queueserver version 0.0.3.post61.dev0+g45f1afb
optional arguments:
-h, --help show this help message and exit
--file-dir FILE_DIR
Directory name where the list of plans and devices is saved. By
default, the list is saved to the file
'existing_plans_and_devices.yaml' in the current directory.
--file-name FILE_NAME
Name of the file where the list of plans and devices is saved. Default
file name: 'existing_plans_and_devices.yaml'.
--startup-dir STARTUP_DIR
Path to directory that contains a set of startup files (*.py and
*.ipy). All the scripts in the directory will be sorted in
alphabetical order of their names and loaded in the Run Engine Worker
environment. The set of startup files may be located in any accessible
directory. For example, 'qserver-list-plans-devices --startup-dir .'
loads startup files from the current directory and saves the lists to
the file in current directory.
--startup-module STARTUP_MODULE_NAME
The name of the module that contains the startup code. The module must
be installed in the current environment For example, 'qserver-list-
plans-devices --startup-module some.startup.module' loads startup code
from the module 'some.startup.module' and saves results to the file in
the current directory.
--startup-script STARTUP_SCRIPT_PATH
The path to the script with startup code. For example, 'qserver-list-
plans-devices --startup-script ~/startup/scripts/script.py' loads
startup code from the script and saves the results to the file in the
current directory.
qserver-zmq-keys¶
Use this tool to generate random public-private key pairs for securing 0MQ control communication channel used by RE Manager:
private key - set as a value of
QSERVER_ZMQ_PRIVATE_KEY_FOR_SERVER
environment variable at workstation or server running RE Managerpublic key - set as a value of
QSERVER_ZMQ_PUBLIC_KEY
environment variable at the workstation(s) running the client application(s).
If server private key is know, the public key may be generated by passing the private
key to qserver-zmq-keys
using --zmq-private_key
.
qserver-zmq-keys -h
displays help information:
$ qserver-zmq-keys -h
usage: qserver-zmq-keys [-h] [--zmq-private-key ZMQ_PRIVATE_KEY]
Bluesky-QServer:
ZMQ security: Generate public-private key pair for ZeroMQ control communication channel.
bluesky-queueserver version 0.0.3.post61.dev0+g45f1afb.
Generate new public-private key pair for secured 0MQ control connection between
RE Manager and client applications. If private key is passed as ``--zmq-private-key``
parameter, then the generated key pair is based on the provided private key.
optional arguments:
-h, --help show this help message and exit
--zmq-private-key ZMQ_PRIVATE_KEY
Private key used by RE Manager. If the private key is provided, then
the public key is generated based on the private key. This option
allows to create (recover) public key based on known private key. The
passed value should be 40 character string containing z85 encrypted
key.
qserver-console-monitor¶
qserver-console-monitor
is a simple application that subscribes to the console output (stdout
and
stderr
) published by RE Manager via 0MQ and prints the received messages to terminal (to stdout
).
The console output printed by the monitor is expected to be identical to the output printed in
RE Manager terminal. The monitor may be run on the same workstation as RE Manager or any computer,
which can access the workstation running RE Manager over the network. If the address of
the 0MQ socket is different from default, it can be passed to the monitor application
as a parameter (--zmq-info-addr
). RE Manager does not publishing the console output
to 0MQ socket by default. Publishing can be enabled by starting RE Manager with the parameter
--zmq-publish-console
:
start-re-manager --zmq-publish-console ON
(see Console Ouput).
qserver-console-monitor -h
displays help information:
$ qserver-console-monitor -h
usage: qserver-console-monitor [-h] [--zmq-info-addr ZMQ_INFO_ADDR]
[--zmq-subscribe-addr ZMQ_SUBSCRIBE_ADDR]
Queue Server Console Monitor:
CLI tool for remote monitoring of console output published by RE Manager.
bluesky-queueserver version 0.0.15
optional arguments:
-h, --help show this help message and exit
--zmq-info-addr ZMQ_INFO_ADDR
The address of RE Manager socket used for publishing console output.
The parameter overrides the address set using QSERVER_ZMQ_INFO_ADDRESS
environment variable. The default value is used if the address is not
set using the parameter or the environment variable. Address format:
'tcp://127.0.0.1:60625' (default: tcp://localhost:60625).
--zmq-subscribe-addr ZMQ_SUBSCRIBE_ADDR
The parameter is deprecated and will be removed. Use --zmq-info-addr
instead.
qserver-clear-lock¶
qserver-clear-lock
allows to clear RE Manager lock stored in Redis. The manager lock
is not cleared by restarting the manager: it must be explicitly cleared using
a valid lock key (used to lock the manager) or an emergency lock key (optional).
If the key is lost and the emergency lock key is not set or known, then the lock
could be cleared by running qserver-clear-lock
and restarting RE Manager application
or service. The utility needs access to Redis server used by RE Manager. If Redis
address is different from default, the correct address must be passed using the parameter
--redis-addr
.
$ qserver-clear-lock -h
usage: qserver-clear-lock [-h] [--redis-addr REDIS_ADDR]
Bluesky-QServer: Clear RE Manager lock.
bluesky-queueserver version 0.0.16.
Recover locked RE Manager if the lock key is lost. The utility requires access to Redis
used by RE Manager. Provide the address of Redis service using '--redis-addr' parameter.
Restart the RE Manager service after clearing the lock.
optional arguments:
-h, --help show this help message and exit
--redis-addr REDIS_ADDR
The address of Redis server, e.g. 'localhost', '127.0.0.1',
'localhost:6379' (default: localhost).