bconf

Submits live reconfiguration requests, updating configuration settings in active memory without restarting daemons.

Synopsis

bconf action object_type=object_name "value_pair[;value_pair...]"] [-c "comment"] [-f]
bconf hist [-l|-w] [-o object_type] [-u user_name] [-T time_period] [-a action] [-f config_file] [history_file]
bconf disable
bconf -h [action [object_type]]
bconf -pack pack_file_name
bconf -V

Action synopsis

addmember usergroup | hostgroup | queue | limit | gpool | serviceclass=object_name "value_pair[;value_pair ...]" [-c "comment"]
rmmember usergroup | hostgroup | queue | limit | gpool | serviceclass=object_name "value_pair[;value_pair ...]" [-c "comment"]
update user | usergroup | host | hostgroup | queue | limit | gpool | serviceclass=object_name "value_pair[;value_pair ...]" [-c "comment"]
create usergroup | limit | serviceclass=object_name "value_pair[;value_pair ...]" [-c "comment"]
delete usergroup | limit | serviceclass=object_name "value_pair[;value_pair ...]" [-c "comment"] [-f]
set user |usergroup | limit=object_name "value_pair[;value_pair ...]" [-c "comment"]
add host=object_name "value_pair[;value_pair ...]" [-c "comment"]

Description

The bconf command is enabled when the LSF_LIVE_CONFDIR parameter is defined in the lsf.conf file.

The bconf command allows configuration changes without restarting LSF or any daemons. Changes are made in active LSF memory, and updated configuration files are written to the directory defined by parameter LSF_LIVE_CONFDIR. Original configuration files are not changed. However, LSF reloads files found in the LSF_LIVE_CONFDIR directory during restart or reconfiguration in place of permanent configuration files.

Important: Before you enable live reconfiguration, run the badmin reconfig command to make sure that all configuration files have no error or warning messages. Merge multiple sections in configuration files where possible. Keep the order of sections and the syntax used in the configuration file templates in all configuration files used with live reconfiguration.

Configuration changes made by using the bconf command cannot be rolled back. Use the bconf command to reverse the configuration requests and undo unwanted configuration changes. You can also manually remove or replace the configuration files in the LSF_LIVE_CONFDIR directory before restart or reconfiguration.

The first bconf command that is executed after restart or reconfiguration backs up the files that were loaded into memory. All files that the bconf command can change are backed up in the LSF_LIVE_CONFDIR directory as *.bak files. The backup files always represent the configuration before bconf commands were run.

Cluster administrators can run all bconf commands. All users can run bconf hist queries. All bconf command requests must be made from static servers.

The gpool administrators can manage the corresponding guaranteed resource pool.

User group administrators with usershares rights can adjust user shares.

User group administrators with full rights can change the following configurations:
  • Adjust user shares and group members
  • Delete the user group
  • Create new user groups

User group administrators with full rights can add a user group member to the user group only if they also have full rights for the member user group. User group administrators who add a user group through the bconf create command are automatically added to the GROUP_ADMIN list with full rights for the new user group.

Important: Remove the configuration files in the LSF_LIVE_CONFDIR directory, or merge files into the LSF_CONFDIR directory before you disable live configuration, upgrade LSF, apply patches to LSF, or add server hosts.

The bconf command supports common configuration changes. The bconf command cannot change all configurations. For time-based configuration, global configurations are changed globally, and configuration for the active time window are changed only for the time window.

The bconf command changes the following configuration files:

  • lsb.resources
  • lsb.queues
  • lsb.users
  • lsb.hosts
  • lsf.cluster.clustername
  • lsb.serviceclasses
Important: Changing these configuration files manually while live reconfiguration is enabled automatically disables the bconf command. Further live reconfiguration requests are rejected.

The bconf command changes objects, or configuration blocks enclosed in Begin and End statements, in the configuration files. One bconf request can affect several configured objects. For example, deleting a user group that appears in the configuration for a limit and a queue also changes the limit and queue configuration, and returns the following confirmation messages:

bconf delete usergroup=ug1
bconf: Request to delete usergroup <ug1> impacts the following:
    <USERS> in limit <limit1>
    <USERS FAIRSHARE > in queue <big_mem_queue>
Are you sure you want to delete usergroup <ug1> (y/n)?

The API corresponding to the bconf command is lsb_liveconfig. For more information, see the IBM Spectrum LSF API reference.

Subcommands and options

action object_type=object_name "value_pair[;value_pair...]"] [-c "comment"] [-f]
action
action is the requested action that is supported by live reconfiguration. The following keywords can be an action value: addmember, rmmember, update, create, add, delete, set.
addmember
Adds a member to the group or list of an existing field in an object, or updates the value of an existing member.

Cannot be used with reserved words such as all, excluded elements such as ~user1 or !host1, or members defined by regular expressions such as hostA[01-10] or hostA*.

When used with an existing member, the value of the member is updated within the object.

rmmember
Removes a member from the group or list of an existing key (field) in an object.
Restriction: You cannot remove all members from groups and lists cannot have all (except USER_SHARES). The group or list cannot contain only reserved words such as others, all, or allremote, or contain only excluded members.

You cannot use the rmmember option with reserved words such as all, excluded elements such as ~user1 or !host1, or members defined by regular expressions such as hostA[01-10] or hostA*. Hosts added with the badmin hghostadd command cannot be removed with the bconf rmmember command.

update
Updates by replacing the old value with the new value, or adding the field if it is not already configured.

Use the update usergroup=group_name or update hostgroup=group_name command to reload an external user group.

create
Creates a new object.
add
Adds a new host.
delete
Deletes an existing object.
You cannot delete a user group under the following conditions:
  • The user group contains running or pending jobs (run the busers command to check)
  • The user group appears in a LSF multicluster capability UserMap section in the lsb.users file
  • The user group is the default user group defined by the DEFAULT_USER_GROUP parameter in the lsb.params file.

Deleted user groups are counted towards the maximum allowed number of user groups until the next restart or reconfig command is run. Deleted user groups might still show in the busers command output.

set
Forces an update or a create action.
object_type
Any block that is enclosed by BeginSection ... EndSection in a configuration file that is changed by a bconf command request. An object includes a type and name and contains attributes that are called keys, which are fields that are defined in the object section of the file. The following keywords can be an object_type value: user, usergroup, host, hostgroup, queue, limit, gpool. Not all actions apply to all object types.
user
Can be used with the following actions and keywords:
  • action - update, set
  • value_pair - the following keywords in the lsb.users file: MAX_JOBS, JL/P, MAX_PEND_JOBS
usergroup
Can be used with the following actions and keywords:
  • action - addmember, rmmember, update, create, delete, set
  • value_pair - the following keywords in the lsb.users file: GROUP_ADMIN, GROUP_MEMBER, JL/P, MAX_JOBS, MAX_PEND_JOBS, PRIORITY, USER_SHARES
host
Can be used with the following actions and keywords:
  • action - update, add
  • value_pair the following keywords in the lsb.hosts file: MXJ, JL/U, EXIT_RATE, io, it, ls, mem, pg, r15s, r1m, r15m, swp, tmp, ut
  • value_pair - the following keywords in the lsf.cluster.clustername file: model, type, resources
hostgroup
Can be used with the following actions and keywords:
  • action addmember, rmmember, update
  • value_pair - the following keyword in the lsb.hosts file: GROUP_MEMBER
queue
Can be used with the following actions and keywords:
  • action - addmember, rmmember, update
  • value_pair - the following keywords in the lsb.queues file: UJOB_LIMIT, PJOB_LIMIT, QJOB_LIMIT, HJOB_LIMIT, FAIRSHARE
limit
Can be used with the following actions and keywords:
  • action - addmember, rmmember, update, create, delete
  • value_pair - the following keywords in the lsb.resources file: QUEUES, PER_QUEUE, USERS, PER_USER, HOSTS, PER_HOST, PROJECTS, PER_PROJECT, SLOTS, SLOTS_PER_PROCESSOR, MEM, TMP, SWP, JOBS, RESOURCE
gpool
Can be used with the following actions and keywords:
  • action - addmember, rmmember, update
  • value_pair - the following keyword in the lsb.resources file: DISTRIBUTION
serviceclass
Can be used with the following actions and keywords:
  • action - create, delete, update, addmember, rmmember
  • value_pair - the following keywords in the lsb.serviceclasses file: ACCESS_CONTROL, DESCRIPTION
object_name
The name of the existing object, or the object that is being created.
value_pair
The key (object attribute) and allowed values that are used in a bconf command request. The value_pair has the form keyword=value, and it uses the same keywords and syntax as in LSF configuration files. Not all LSF configuration keywords can be used with all actions.

Use a semicolon to separate multiple value_pair entries. Use a dash - or empty parentheses () to reset keywords to default values, depending on the keyword in the LSF configuration files.

For more information about allowed actions, objects, and keywords, use the help command bconf -h action object.

Examples
bconf -h addmember hostgroup
bconf addmember hostgroup=hgroupA "GROUP_MEMBER = host1"

bconf rmmember hostgroup=hgroupA "GROUP_MEMBER=host1 host2"

bconf update host=host1 "MXJ=10; JL/U=5"

bconf create usergroup=groupA "GROUP_MEMBER=(elaine tina toby); USER_SHARES=([elaine,10] 
[default,5]); MAX_JOBS=500; MAX_PEND_JOBS=10000"

bconf rmmember queue=normal "FAIRSHARE=USER_SHARES[[joe, 10]]"

bconf addmember serviceclass=sla2 "ACCESS_CONTROL=QUEUES[normal]"

-c "comment"
Logs the text of comment as an administrator comment in the liveconf.hist file. The maximum length of the comment string is 512 characters. Embed the comment in double quotation marks, and do not include the new line character (\n).
-f
Disables interaction and forces bconf delete command requests to run without confirmation. Applies only to the delete action.
hist [-l|-w] [-o object_type] [-u user_name] [-T time_period] [-a action] [-f config_file] [history_file]
Queries the bconf command history file liveconf.hist located under the $LSB_SHAREDIR/cluster_name/logdir directory, or queries a specific history file (history_file). Output is filtered by the specified criteria. By default, only bconf command requests made by the current user are displayed.
-l
Long display format.
-w
Wide display format.
-o object_type
Displays entries that include the specified object_type. The following object_type values are supported: user, usergroup, host, hostgroup, queue, limit, gpool, serviceclass.
-u user_name
Displays entries for requests that are made by the specified user. To display bconf command requests from all users, specify the -u all option.
-T time_period
Displays entries within the specified time period. For syntax, see "Time Interval Format" in the bhist command reference.
-a action
Displays entries that include the specified action. The following action values are supported: addmember, rmmember, update, create, add, delete.
-f config_file
Displays entries that include the specified config_file. The following config_file values are supported: lsb.resources, lsb.queues, lsb.users, lsb.hosts, lsf.cluster.clustername, or lsb.serviceclasses.
history_file
Displays entries from the specified history file. By default, the history file is liveconf.hist.
disable
Blocks all bconf command requests until the next reconfiguration or restart of daemons with the badmin reconfig, badmin mbdrestart, or lsadmin reconfig commands (for manual changes to lsf.cluster file). Use the disable option before you change configuration manually files to make sure that you are editing files corresponding to the current configuration. Only the primary cluster administrator can disable live reconfiguration.
-h [action [object_type]]
Prints command usage to stderr and exits. Use for more information about allowed actions, objects, and the keywords that can be used with each object type.
bconf -h action
Lists allowed object types for the specified action.
bconf -h action object_type
Lists allowed value pairs for the specified action and object_type. If both action and object_type are specified, you can omit the -h option.
-pack
Reads multiple requests and sends them to mbatchd at the same time. bconf reads and parses the text file, with each line an individual bconf request. However, the requests are grouped together and sent to mbatchd at one time. If a line in the request fails, bconf -pack stops at that line.
-V
Prints LSF release version to stderr and exits.

bconf hist default output

The bconf hist command displays the bconf command events in shortened form, without comments or details of affected objects. Column content is truncated as required and marked with an asterisk (*).

TIME
Time of the bconf request.
OBJECT
The type of object specified.
NAME
The name of the object specified.
ACTION
Action that is performed on the object.
USER
User who made the bconf request.
IMPACTED_OBJ
All objects that are changed as a result of the bconf request.
bconf hist -u all
TIME                 OBJECT    NAME   ACTION   USER   IMPACTED_OBJ 
Nov 9 15:19:50 2010  limit     aaa    create   ellen  limit=aaa 
Nov 9 15:19:46 2010  limit     aaa    update   leyang limit=aaa 
Nov 9 15:19:37 2010  usergroup ug1    delete   ellen  queue=normal owners* 
                                                      limit=bbb
                                                      usergroupr=ug1
Nov 9 15:19:28 2010  queue     normal update   leyang queue=normal 
Nov 9 15:19:10 2010  host      host1  update   ellen  host=host1 

bconf hist wide output (-w)

Wide output displays the same columns, but without truncating column contents.
bconf hist -w
TIME                 OBJECT    NAME    ACTION   USER     IMPACTED_OBJ 
Nov  9 15:19:50 2011 limit     aaa     create   ellen    limit=aaa 
Nov  9 15:19:46 2011 limit     aaa     update   leyang   limit=aaa 
Nov  9 15:19:37 2011 usergroup ug1     delete   ellen    queue=normal owners q1 q2 q3; limit=bbb; 
usergroup=ug1

bconf hist long output with the -l option

Long output displays all details of the requested bconf command events, including the new value of each affected object. Names of changed configuration files are included.
bconf hist -l
Mon Nov 18 15:19:45 2009: Limit <aaa> created by user <admin1> with requested values 
<PER_HOST=all; RESOURCE=[A,5]; USERS=ug1 ug2 ug3> and comments <This is an example of a create
 action on a limit object named aaa.>
Changes made:
Limit <aaa> created in lsb.resources with <PER_HOST=all; RESOURCE=[A,5]; USERS=ug1 ug2 ug3>
---------------------------------------------------------
Mon Nov 18 15:19:45 2009: Usergroup <ug1> deleted by user <admin1> with comments <This is an 
example of a delete action on a usergroup object named ug1.>
Changes made:
Usergroup <ug1> deleted in lsb.users
Limit <aaa> updated in lsb.resources with <USERS=ug2>
Queue <owners> updated in lsb.queues with <USERS=ug2 ug3>
---------------------------------------------------------
Mon Nov 18 15:19:45 2009: Queue <q1> updated by user <admin2> with requested values 
<FAIRSHARE=USERSHARE[[ellen, 2]];QJOB_LIMIT=10> and comments <This is an example of an update
 action on a queue object named q1.>
Changes made:
Queue <q1> updated in lsb.queues with <QJOB_LIMIT=10>
---------------------------------------------------------
Mon Nov 18 15:19:45 2009: Limit <aaa> member added by user <admin2> with requested values 
<USERS=julie> and comments <This is an example of an addmember action on a limit object named 
aaa.>
Changes made:
Limit <aaa> updated in lsb.resources with <USERS=ellen user4 julie>
---------------------------------------------------------
Wed Jul 28 17:16:28 2010: Host <host78> added by user <usr9> with requested value <mem=500/100>
Changes made:
Host <host78> added in <lsf.cluster.x123> with <hostname=host78>
Host <host78> added in <lsb.hosts> with <HOST_NAME=host78; MXJ=!; mem=500/100>
---------------------------------------------------------
Wed Jul 28 17:17:08 2010: Host <host78> updated by user <usr9> with requested value <mem=500/100>
Changes made:
Host <host78> updated in <lsb.hosts> with <mem=500/100>

Diagnostics

If the command ran correctly, the exit code is 0. A negative exit code the number of key-value pairs that contain errors.

See also

lsb.queues, lsb.hosts, lsb.resources, lsb.serviceclasses, lsb.users, lsf.cluster, lsf.conf