admfailovervtc(1M) DG/UX R4.11 admfailovervtc(1M)
NAME
admfailovervtc - manage VTC/PTC Failover
SYNOPSIS
admfailovervtc -o add [ -h hostname -r remote-backup-controller-name
] [ -l local-backup-controller-name ] [ -sS ] primary-
controller-name
admfailovervtc -o delete [ -S ] primary-controller-name ...
admfailovervtc -o modify [ -h hostname -r remote-backup-controller-
name ] [ -l local-backup-controller-name ] [ -sS ]
primary-controller-name
admfailovervtc -o list [ -qv ] [ primary-controller-name ... ]
admfailovervtc -o switch [ -s ] primary-controller-name
admfailovervtc -o give -h hostname [ primary-controller-name ... ]
admfailovervtc -o take -h hostname [ -T ] [ primary-controller-name
... ]
admfailovervtc -o start [ primary-controller-name ... ]
admfailovervtc -o stop [ primary-controller-name ... ]
admfailovervtc -o sync -h hostname
where:
primary-controller-name
local-backup-controller-name
remote-backup-device-name The formal name of a VTC/PTC.
DESCRIPTION
The admfailovervtc command is used to manage the VTC/PTC failover
database and those controllers that are listed in that database. See
failover(4M) for a description of the VTC/PTC failover database. By
using VTC/PTC failover, servers can now provide a highly available
level of asynchronous connection services. This capability is
achieved by providing the means to activate a "local" or "remote
backup" controller with the same configuration information that was
used by the system to activate the "primary" controller.
In order to use the remote failover features of the admfailovervtc
command, you must have the Failover package installed.
Note that all connections are lost as part of the failover process
and the user is responsible for re-establishing any "call-in"
connections (e.g. telnetin, rlogin) after the backup controller is
activated. Remote VTC/PTC failover functionality depends on the
presence of a dual-initiator configuration and the user having
already set up physical disk failover.
For an individual entry in the VTC/PTC failover database, the
expression, "locally enabled controller", is used to refer to the
VTC/PTC that has configuration information specified in the local
vtc.addrs(4M) file. The locally enabled controller is either the
primary VTC/PTC or local backup VTC/PTC for a particular entry in the
database. The expression, "VTC/PTC configuration files" is used to
refer to all files in the /etc/tcload directory (i.e. vtc.addrs(4M)
and vtc_snmp_files(4M)). Both of these expressions are used
throughout this document.
Operations
add Add a VTC/PTC failover database entry. At least one backup
controller must be specified. A VTC/PTC must be removed
from all VTC/PTC configuration files before being added as
a backup controller. A VTC/PTC must have a device entry in
the local vtc.addrs(4M) file before being added as a
primary controller. This operation will add the specified
VTC/PTC failover database entry and can optionally start
the use of the primary controller and/or synchronize the
VTC/PTC failover database with the host that contains the
remote backup controller. Both a local and remote backup
controller may be specified for a single VTC/PTC failover
entry.
delete Delete a VTC/PTC failover database entry. This operation
will delete the specified database entry. Note that the
active controller for this entry is not stopped as a result
of this operation, but the failover relationship is ended.
modify Modify a VTC/PTC failover database entry. This operation
will modify the specified database entry, and can
optionally start the use of the database entry and/or
synchronize the VTC/PTC failover database with the host
that contains the remote backup controller.
list List VTC/PTC failover database entries. The list operation
reports the following VTC/PTC failover information:
name of the primary controller
name of host that contains the remote backup controller
name of the remote backup controller
name of the local backup controller
flag indicating which controller (if any) is active
flag indicating which controller is the locally enabled controller
switch Switch which VTC/PTC is the locally enabled controller on
this host. This operation is only valid if a local backup
controller is specified for this primary VTC/PTC failover
database entry. The switch operation swaps entries for the
locally enabled controller in all VTC/PTC configuration
files and the devlinktab(4M) file with the locally disabled
controller. This operation then executes chk.devlink(1M).
give Give control of VTC/PTC connection services to another host
in a dual-initiator VTC/PTC failover configuration. This
operation stops the active controller on this host, which
results in all active connections being terminated. The
remote backup controller is then started with the same
configuration information that was used by the system to
activate the locally enabled controller. This operation
should be used in conjunction with the give operation of
the admfailoverdisk(1M) command. When a configuration is
using Machine Initiated Failover, the following command
should be added to the regain-pulse script which is
executed by the failovermon(1M) monitor to return control
of connection services to all VTCs/PTCs in the failover
configuration on the host that it was monitoring:
admfailovervtc -o give -h <hostname>
take Take control of connection services from another host in a
dual-initiator VTC/PTC failover configuration. This
operation stops the active controller, which results in all
active connections being terminated. The locally enabled
controller is then started with the same configuration
information that was used by the remote system to activate
the corresponding locally enabled controller on that
system. This operation should be used in conjunction with
the take operation of the admfailoverdisk(1M) command.
When a configuration is using Machine Initiated Failover,
the following command should be added to the lost-pulse
script that is to be executed by the failovermon(1M)
monitor to start all locally enabled controllers on this
host that are part of a failover configuration with the
specified remote host:
admfailovervtc -o take -h <hostname> -T
start Start the locally enabled controller for the specified
entry in the VTC/PTC failover database. The default
Internet Address as specified in the local vtc.addrs(4M)
file is first "ping"ed to see if it is already in use by
another host in the failover configuration. If a local
backup controller exists then a daemon monitoring the
locally enabled controller is also started. The daemon
will automatically execute a "switch" operation if it
determines that the locally enabled controller has stopped
responding. Note that if the locally enabled controller is
active, it will be stopped and restarted as a result of
this operation. This operation is automatically performed
when a system is booting.
stop Stop the controller that is active for the specified
VTC/PTC failover database entry on this host. This
operation will results in stopping the primary controller
or local backup controller, depending on which one is
active. This operation is automatically performed when a
system is shutting down.
sync Synchronize VTC/PTC failover databases. This operation
will synchronize all the failover(4M) databases, all
VTC/PTC configuration files, and the devlinktab(4M) file on
this host with the specified remote host. This operation
determines a common set of available tty numbers to be used
by both the primary, local backup, and remote backup
controllers. The vtc.addrs(4M) and devlinktab(4M) files,
are modified on both systems to reflect the changes in tty
number assignments so that chk.devlink(1M) can be executed
on both systems. This operation should be executed any
time changes are made to the devlinktab(4M) file or any of
the VTC/PTC configuration files for entries corresponding
to controllers that are part of a VTC/PTC failover
configuration involving another host.
Options
The following option is required for the give, take, and sync
operations, and is optional on the add and modify operations:
-h hostname
This is the name of the host that contains the remote
backup controller(s).
The following options can be used with the add and modify operations:
-r remote-backup-controller-name
This is the name of the remote backup VTC/PTC.
-l local-backup-controller-name
This is the name of the local backup VTC/PTC.
The following option can be used with the add, delete, and modify
operations:
-S Synchronize all the failover(4M) databases. This option
will cause the failover(4M) databases, the devlinktab(4M)
file, and all VTC/PTC configuration files to be
synchronized upon successful completion of the current
operation.
The following option can be used with the add, modify, and switch
operations:
-s Start the locally enabled controller for the specified
entry in the VTC/PTC failover database upon successful
completion of the current operation.
The following options can be used with the list operation:
-q Quiet. Produce an unformatted listing with no headers,
fields delimited by a single space.
-v Verbose. Produce a formatted listing with headers and
aligned columns. This option is the default.
The following option can be used with the take operation:
-T Trespass. Unconditionally take control of the connection
services for the specified VTC/PTC. This option should be
used if the host you are taking the connection services
from has failed.
EXAMPLES
To add an entry to the VTC/PTC failover database for syac(vme(0),0)
with syac(vme(0),1) as a local backup VTC, you should execute the
following command line:
admfailovervtc -o add -l 'syac(vme(0),1)' 'syac(vme(0),0)'
To then start the primary VTC, syac(vme(0),0), you should execute the
following command line:
admfailovervtc -o start 'syac(vme(0),0)'
This will also start a daemon that will monitor the primary VTC. The
daemon will automatically execute a switch operation if the primary
VTC stops responding.
To then manually switch from the primary VTC, syac(vme(0),0), to the
local backup VTC, syac(vme(0),1), you should execute the following
command line:
admfailovervtc -o switch -s 'syac(vme(0),0)'
Note that this is the same command the daemon will automatically
execute if it detects that the primary VTC, syac(vme(0),0), stops
responding. This operation will swap the primary VTC,
syac(vme(0),0), with the local backup VTC, syac(vme(0),1) in all
VTC/PTC configuration files, the devlinktab(4M) file, and then
execute chk.devlink(1M). This operation will then stop the primary
VTC and start (i.e. -s option) the local backup VTC. Note that this
will cause all connections to the primary VTC, syac(vme(0),0), to be
lost and will start a daemon that will automatically "switch" back to
the primary VTC, syac(vme(0),0), if the local backup VTC,
syac(vme(0),1), stops responding.
To expand a PTC failover database entry that contains a primary PTC,
spac(pci(0),0,0), to include a remote backup PTC, spac(pci(0),2,0),
that exists on hostb, you should execute the following:
admfailovervtc -o modify -h hostb -r 'spac(pci(0),2,0)' 'spac(pci(0),0,0)'
To then synchronize the PTC failover(4M) databases of hosta (the
local host) and hostb, you should execute the following:
admfailovervtc -o sync -h hostb
To then give control of the PTC connection services for the locally
enabled PTC on hosta to the corresponding remote backup PTC on hostb,
you should execute the following command line:
admfailovervtc -o give -h hostb 'spac(pci(0),0,0)'
FILES
/etc/failover failover database files
/etc/tcload directory for VTC/PTC configuration files
/etc/devlinktab device link table file
DIAGNOSTICS
Warnings
- An attempt was made to stop the locally enabled controllers
and it was determined that both the primary and local backup
controllers were active.
Errors
- An attempt was made to add a controller to the VTC/PTC
failover database that already exists in the database.
- An attempt was made to add a VTC/PTC failover database entry
specifying the same controller for both the primary and local
backup controllers.
- An attempt was made to start, stop, modify, delete, give, or
take, an entry that does not exist in the VTC/PTC failover
database.
- An attempt was made to start or switch the locally enabled
controller, but neither the primary nor local backup
controllers were present in the local vtc.addrs(4M) file.
- An attempt was made to start the locally enabled controller
for which the IP address specified in the local vtc.addrs(4M)
file is already in use on the network. This most likely
indicates that the remote backup controller is active.
- An attempt was made to specify a controller name that is
either not configured or not really a VTC/PTC.
Exit Codes
0 The operation was successful.
1 The operation was unsuccessful.
2 The operation failed due to access restrictions.
3 There was an error in the command line.
SEE ALSO
admfailoverdisk(1M), failovermon(1M), failover(4M), failoverd(1M),
syac(7), vtc.addrs(4M), vtc_snmp_files(4M), devlinktab(4M),
chk.devlink(1M), appropriate_privilege(5), cap_defaults(5).
NOTES
You must have appropriate privilege to perform all operations except
list. For systems supporting the DG/UX Capability Option,
appropriate privilege is defined as having one or more specific
capabilities enabled in the effective capability set of the user.
See cap_defaults(5) for the default capabilities for this command.
On systems without the DG/UX Capability Option, appropriate privilege
means that your process has an effective UID of root. See the
appropriate_privilege(5) man page for more information.
The start and list operations may take several seconds to complete,
since they attempt to determine whether or not an IP address is
active. The switch and sync operations may take a few minutes to
complete, since they manage a large number of files.
Licensed material--property of copyright holder(s)