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]Action synopsis
addmember usergroup | hostgroup | queue | limit | gpool | serviceclass=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.
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.
- 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.
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
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_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.
Examplesbconf -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)
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
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