This article applies to BoKS Manager 7.0.0.


The GID number, the Host Group prefix and the group name of a Unix group can be changed with the groupadm command by using the -m option. If there are multiple groups with the same GID number and group name, it is not possible to change the group name or the GID number for one group at a time if there are overlapping Host Groups, i.e. if one or more hosts are common Host Group members. In this case you must either remove the conflicting hosts from the Host Groups or apply the change on all groups in a single operation. At time of writing (Feb 2017) there is no support in the groupadm program for changing the GID or the group name of multiple groups at once.


This procedure makes use of the ability to change the Host Group prefix of the Unix group in BoKS to an empty Host Group, i.e a Host Group without any host members. When this is done the users will be removed from the Unix group on the hosts and the Unix group itself will be removed on the hosts. This will also remove the conflicts since there are no longer any overlapping hosts. We can then change the GID of the Unix groups in BoKS and again change the Host Group prefix back to the original setting.


I have two Unix groups defined in BoKS for which I would like to change the GID:

  • DEV:grptst gid=4712
  • TEST:grptst gid=4712

I want to change the GID to 4713.

First make sure there are no conflicting Unix groups in BoKS with GID 4713. You can use the attached utility script (see the bottom of this article for a link to the script) to get a report of conflicting groups. You can run it on the Master or a Replica:

# -i 4713 -g DEV -g TEST

To get a list of all Unix groups registered in BoKS:

# groupadm -l

To get a list of all Host Groups:

# hgrpadm -l


# lh -g

If there are no conflicts, we can continue the procedure.

Create temporary empty Host Groups, i.e. with no members:

# hgrpadm -A -g X_DEV
# hgrpadm -A -g X_TEST

Change the Host Group prefix for the Unix groups temporarily:

NOTE: This will implicitly remove the groups from /etc/group on all affected hosts
and will thus potentially queue up a lot of updates for BoKS Server Agents.

# groupadm -m -n DEV:grptst -r X_DEV:grptst -c 'Changing hostgroup prefix temporarily'
# groupadm -m -n TEST:grptst -r X_TEST:grptst -c 'Changing hostgroup prefix temporarily'

Change the GID to 4713:

# groupadm -m -n X_DEV:grptst -i 4713 -c 'Changing GID'
# groupadm -m -n X_TEST:grptst -i 4713 -c 'Changing GID'

Before continuing we may want to check the status of the client batch queue on the Master and give it some time to drain if needed:

# boksdiag fque -bridge

The queue between the boks_master daemon and boks_drainmast should be short or empty:

# boksdiag fque -master

Change the Host Group prefix back.
This will add the records back to /etc/group on Server Agents and again (potentially) create a lot of queued group file updates on the Master:

# groupadm -m -n X_DEV:grptst -r DEV:grptst -c 'Changing hostgroup prefix back to normal'
# groupadm -m -n X_TEST:grptst -r TEST:grptst -c 'Changing hostgroup prefix back to normal'

Remove the empty Host Groups:

# hgrpadm -d -g X_DEV

# hgrpadm -d -g X_TEST


Changing the GID number of a Unix group does not affect the assignment of primary group to users. You can change the primary group for a user with modbks -l user -g gid

The above procedure does not work (i.e. will not have any effect) on AIX Server Agents, if the old GID number is assigned as primary GID to one or more users on these hosts.

Depending on the size of the Host Groups involved, this procedure can potentially create a large amount of updates to Server Agents. That in turn can affect the database replication performance. In that case Fox Technologies recommends that hotfix HFBM-0168 is installed before performing these actions.

Link to the utility script.

Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: May 25, 2018