Anda di halaman 1dari 13

PowerChute

TM
Network
Shutdown
Configuration Files


PCNSconfig.INI ii

Table of Contents
1 Introduction .................................................................................................................................... 1
2 INI File Format Overview ................................................................................................................ 1
2.1 Format ................................................................................................................................... 1
2.1.1 Properties.......................................................................................................................... 1
2.1.2 Sections ............................................................................................................................. 1
2.1.3 Comments ......................................................................................................................... 1
3 Using the Configuration INI File...................................................................................................... 2
3.1 Import and Export of Configuration ...................................................................................... 2
3.2 Editing PowerChute INI ......................................................................................................... 2
4 INI File Validation............................................................................................................................ 3
4.1 Missing and Malformed Entries............................................................................................. 3
4.2 Duplicate Entries.................................................................................................................... 3
4.3 Missing Configuration File..................................................................................................... 3
4.4 INI Error Messaging ............................................................................................................... 3
5 PCNSConfig.INI: Sections, Properties, and Values .......................................................................... 5
5.1 NMC Configuration................................................................................................................ 5
5.2 Event Log Configurations....................................................................................................... 6
5.3 Shutdown Configurations ...................................................................................................... 6
5.4 Networking Configurations ................................................................................................... 7
5.5 Event Configurations ............................................................................................................. 7
5.5.1 Event Names ..................................................................................................................... 7
5.5.2 Multiple-UPS Advanced Configuration ........................................................................... 10




PCNSconfig.INI 1
1 Introduction
Prior to version 3.0 of PowerChute Network Shutdown (PCNS), configuration data was stored in a
proprietary binary file. Users found configurations difficult to implement and distribute with this
method.
From version 3.0, PCNS has a text-based INI configuration store for PowerChute. The document
outlines the format of this INI file, and how it can be used.
Here is an outline of the sections, with links:
Section 2, INI File Format Overview, introduces some basic rules for the formatting of INI files.
Section 3, Using the Configuration INI, shows how to access the INI file, and how to edit it manually.
Section 4, INI File Validation, details how configuration properties are validated by PowerChute.
Section 5, PCNSConfig.INI: Sections, Properties, and Values, details the valid sections, properties, and
values expected in the PowerChute configuration INI.
2 INI File Format Overview
The INI file format is the de facto standard for configuration files. INI files are simple text files with a
basic structure. They are commonly associated with Microsoft Windows, but are also used on other
platforms.
2.1 Format
2.1.1 Properties
The basic element in an INI file is the property. Every property has a name and a value, delimited by
an equals sign (=). The name appears to the left of the equals sign.
For example:
name = value
2.1.2 Sections
Properties may be grouped into arbitrary, named sections. The section name appears on a line by
itself, in square brackets ([ and ]). All properties after the section declaration are associated with
that section. There is no explicit end of section delimiter; sections end at the next section
declaration, or the end of the file. Sections may not be nested.
For example:
[Section]
2.1.3 Comments
Semicolons (;) indicate the start of a comment. Comments continue to the end of the line.
Everything between the semicolon and the end of the line is ignored.
For example:
; This is a comment


PCNSconfig.INI 2
3 Using the Configuration INI File
PowerChute Network Shutdown (PCNS) 3.0 is introducing an INI file where configuration values will
be read from and written to. This section describes how the application will handle this file.
3.1 Import and Export of Configuration
PowerChute Network Shutdown configurations will be held in INI format in the install directory at:
<install dir>\group1\pcnsconfig.ini
<install dir>\group1\pcnsconfig.ini.bak
When configuration options are changed using the user interface, these are written to these INI files.
Some sensitive values are never written to the configuration file, such as usernames or passwords.
The configuration INI file is imported automatically when PowerChute Network Shutdown server
starts. Its contents are validated, and several errors written to the PCNS Event Log.
PCNS reads from the INI file as needed. This may also result in validation failures, if the properties,
values, or formats sought are missing or invalid.
Pcnsconfig.ini.bak represents the backup INI file. When reading from the main INI, if a validation
error occurs, the last known good value is sought in the backup. This is also validated by the specific
rules applied to each property. If this value can be substituted, it is, and an error or warning is
written to the PCNS Event Log to note the validation failure of the main INI value.
This value then overwrites the value in the main INI, providing a self-correcting mechanism.
Similarly, if the backup INI value is missing or invalid, a default value is substituted, if appropriate.
3.2 Editing PowerChute INI
As configuration values are modified at the PCNS user interface, these values are written to the
configuration INI files. For example, as you enable events for shutdown or notification, the
configuration INI is automatically updated to reflect these configuration changes.
To edit the INI file manually, it is best to stop the PCNS service. This prevents your modifications
been overwritten by the service as it runs. The INI file can be edited using any text editor. All
sections, properties, values, and formats are specified in section 5 of this document.


PCNSconfig.INI 3
4 INI File Validation
This section describes how PowerChute Network Shutdown (PCNS) validates the properties
contained in the configuration INI.
4.1 Missing and Malformed Entries
An entry is considered missing if it is not available in both the main and backup INI files. In this case,
a validation error is generated, and the value replaced by a default value (if appropriate).
If an entry is missing from the main INI file, but present in the backup INI file, then the entry is
considered malformed. Malformed parameters also include those which cannot be converted to
their expected type, are out of range, fail to match a regular expression, etc.
When this happens, PCNS looks for the last known good value in the backup INI file. Either this, or a
default (if appropriate) value in the case of a missing backup entry are applied, and a validation error
occurs.
The severity of the error depends on the particular parameter.
4.2 Duplicate Entries
PowerChute Network Shutdown does not expect duplicate entries in valid INI sections. If duplicate
entries are present, a validation error will note the presence of duplicate entries.
PCNS will attempt to apply the first value specified in the section only. This value is subject to the
usual validation rules for that property. If the property is invalid, additional validation errors and
warnings will occur.
For example, see the following INI text:
[NetworkManagementCard]
port = 80
port = 81
In this case the value applied by PCNS will be 80. A validation error would also be generated due to
duplicate properties in this NetworkManagementCard section.
4.3 Missing Configuration File
In the case of a missing INI file, PCNS relies on its internal configuration store. If the values sought
cannot be found there, a missing INI file could result in PCNS warning that safe shutdown cannot be
guaranteed.
4.4 INI Error Messaging
As the INI file and its contents are validated, a number of error messages might be generated. These
appear in the event log. These messages are given in the table below.
INI Validation Messages
Reason Message Text Values
A required section is missing from the ERROR: The ini file is missing the 0: The section name


PCNSconfig.INI 4
Reason Message Text Values
INI file. required {0} section.
The INI contains values in the global
area (outside of a section).
WARNING: The ini file has
entries defined outside of a
section.

An unrecognised section is defined in
the INI file.
WARNING: The invalid section
{0} should be removed from the
ini file.
0: The section name
An INI property is missing. This will only
occur if a property is missing from both
main and backup INI files.
ERROR: The ini file is missing {1}
key from section {0}.
0: The section name.
1: The property
name.
No NMC card details are specified in the
INI file.
ERROR: The ini file could not find
IP address information in section
{0}.
0: The name of the
Network
Management Card INI
Section.
Duplicate properties are detected within
a section.
WARNING: The ini file has
detected duplicate values for {1}
in section {0}.
0: The section name.
1: The property
name.
Unrecognised additional properties are
defined in sections.
WARNING: The invalid key {1}
should be deleted from section
{0} in the ini file.
0: The section name.
1: The property
name.
An invalid value for a property is
specified. A substitute value is
unavailable. (Substitute values are
sought in the backup INI file, or a
defined default is used).
ERROR: The ini contains an
invalid value for {1} in section
{0}.
0: The section name.
1: The property
name.
An invalid value for a property is
specified. A substitute value is available.
Substitute values are sought in the
backup INI file, or a defined default is
used.
ERROR: The ini contains an
invalid value for {1} in section
{0}. Using {2} instead. Please
validate the configuration.
0: The section name.
1: The property
name.
2: The substitute
value.
The INI files are missing. FATAL ERROR: PCNS cannot find
the configuration file ({0}) or the
backup configuration file ({1}).
Shutting down.
0: The main INI file
path.
1: The backup INI file
path.
A property value failed to match its
validating regular expression.
ERROR: The key {1} in section {0},
failed to match the supplied
regular expression.
0: The section name.
1: The property
name.
The property value could not be
converted to its expected type.
ERROR: Could not convert the
value of {1} in section {0} to its
expected type.
0: The section name.
1: The property
name.
An event is enabled for command file
execution, but one of the command
parameters has failed validation.
ERROR: Event {0} is enabled for
command file execution, but an
invalid value for {1} is specified.
0: The event.
1: The parameter
which has failed
validation.
An event is enabled for command file
execution, but one of the command
parameters has failed validation.
WARNING: Disabling command
file execution for event {0} due
to bad parameters. Please
validate the configuration.
0: The event.


PCNSconfig.INI 5
5 PCNSConfig.INI: Sections, Properties, and Values
This section describes the valid sections, properties, and values which can be contained in the
PowerChute Network Shutdown (PCNS) configuration INI. Other values will result in validation errors
being written to the PowerChute Event Log.
5.1 NMC Configuration
Section Name: [NetworkManagementCard]
Property Format Default Description
Mode One of single,
redundant, or
parallel.
single Specifies single-UPS,
redundant, or parallel
configuration.
IP_1 to IP_9 IP Address
XXX.XXX.XXX.XXX
N/a Specifies up to nine
IP addresses.
IP_1_Outlet to
IP_9_Outlet
0 = Main Outlet,
1 = Switched Outlet
1, 2 = Switched
Outlet 2 etc
When your UPS has Switched
Outlets, this specifies the
Outlet Group that supplies
power to the PCNS server.
port Integer 80 HTTP port for NMCs.
username 3-10 Alphanumeric
characters (A-Z, a-z,
0-9)
apc Username for NMC
communication. This is also
the username for PCNS.
password 3-32 Alphanumeric
characters (A-Z, a-z,
0-9)
apc PCNS password.
authenticationPhrase 15-32 Alphanumeric
characters (A-Z, a-z,
0-9)
admin user phrase Authentication phrase for
NMC communication. This is
also the authentication phrase
for PCNS.
protocol HTTP or HTTPS HTTP Communications protocol for
the UPS NMC.
acceptCerts true/ false false This is used when PCNS is
configured to register with an
SSL-enabled NMC. When set
to true, PCNS will accept Self-
Signed SSL certs from the
NMC.
enrolWithNMC true/ false true PCNS will automatically enrol
with the target NMC(s) on
service start-up. This can be
disabled by setting this value
to false.
The username, password and authenticationPhrase values can be read from the INI file by PCNS. For
security, these values are not written to the file. Once PCNS reads these values from the INI file, they
are deleted automatically.


PCNSconfig.INI 6
To reset passwords, edit the INI file and place a new username or password value. When the service
restarts, the new username and password will be used.
5.2 Event Log Configurations
Section Name: [EventLog]
Property Default Min Max Format Description
logsize 1000 500 10000 Integer Maximum number of rows in the log
file.
logfile EventLog.txt N/a N/a Quoted file
path.
Path to log file.

5.3 Shutdown Configurations
Section Name: [Shutdown]
Property Default Min Max Format Description
shutdownCommand Default
value will
be
platform
specific.
- - Quoted
file path.
Path to the operating
system shutdown
executable.
shutdownCommandDuration 60 0 7200 Integer The amount of time (in
seconds) the shutdown
command will take to shut
down the operating
system.
shutdownCommandFile - - Quoted
file path
Full path to an optional
shutdown command file
(script).
If the path to a command
file that does not exist is
entered a validation error
will occur and an event is
written to the Event Log.
On Unix systems there is
also a validation check
that the script has execute
permissions.
shutdownCommandFileDuration 30 0 7200 Integer The time (in seconds) the
shutdownCommandFile
will take to execute.
turnOffUps false - - true/false The value indicating if this
PCNS agent should turn
off the UPS after
shutdown.
This is not applicable to
Parallel Silcon UPS,
Smart-UPS VT or Galaxy.


PCNSconfig.INI 7
Property Default Min Max Format Description
turnOffSOG false true/false The value indicating if
PCNS should turn off the
Switched Outlet group it is
attached to after
shutdown.
This applies to an Outlet
Aware UPS only.
shutdownDelay 10
seconds
0 7200 Integer The amount of time PCNS
will wait before starting to
shut down the OS.

5.4 Networking Configurations
Section Name: [Networking]
Networking Properties, Values
Property Default Min Max Format Description
localHostAddress - - IP Address
XXX.XXX.XXX.XXX
The IP address of the PCNS
agent. This is used for
registering with the NMC.
protocol HTTP - - HTTP or HTTPS Toggles between HTTP and
HTTPS (SSL) for the web user
interface.
HTTPPort 3052 - - Integer. See validation
note below.
HTTP port.
HTTPSPort 6547 - - Integer. See validation
note below.
HTTPS port.
The valid HTTP ports are:
80,
3052,
5000 to 32768.
The valid HTTPS ports are:
443,
6547,
5000 to 32768.
5.5 Event Configurations
Section Name: [Events]
5.5.1 Event Names
This section describes the event names which can appear in the configuration INI file. Property
names in the Event section are prefixed with the name pattern event_<EventName>_.


PCNSconfig.INI 8
A typical configuration for the PowerFailed event would appear as:
[Events]
event_PowerFailed_enableLogging = true
event_PowerFailed_enableCommandFile = false
event_PowerFailed_commandFilePath =
event_PowerFailed_commandFileDelay = 0
event_PowerFailed_commandFileDuration = 0
event_PowerFailed_enableShutdown = false
event_PowerFailed_shutdownDelay = 120
UPS Event Names
Event Name Configurable in the PCNS UI?
PowerFailed Yes UPS: On Battery
PowerRestored Yes Input Power: Restored
Overload Yes UPS: Overloaded
OverloadSolved Yes UPS Overload: Corrected
RuntimeExceeded Yes Runtime: Exceeded
RuntimeWithinRange Yes Runtime: Normal Again
BatteryDischarged Yes Battery: Discharged
BatteryChargeInRange Yes Battery: Recharged
LowBattery No
FaultBypassEnabled Yes Bypass: Due to a Fault
BypassEnabled Yes Bypass: For Maintenance
BypassDisabled Yes Bypass: Ended
BypassContactorFailed Yes Bypass Switch: Failed
BypassContactorOk Yes Bypass Switch: Replaced
CommunicationLostWhileOnBattery Yes Communication Lost: While on Battery
CommunicationLost Yes Communication: Management Card cannot
communicate with the UPS.
NetCommunicationLost Yes Communication: PowerChute cannot
communicate with the Management Card
CommunicationEstablished Yes Communication: Established
MinRedundancyLost Yes Minimum Redundancy: Lost
MinRedundancyRegained Yes Minimum Redundancy: Regained
MaxInternalTempExceeded Yes UPS Temperature: Overheated
MaxInternalTempInRange Yes UPS Temperature: Normal Again
MinLoadCapabilityLost Yes Load (kVA) Alarm Violation
MinLoadCapabilityRegained Yes Load (kVA) Alarm Violation: OK
PowerSourceTurnOffInitiated No UPS Turn off started
ShutdownStarting No OS shutdown has started
AccountLockOut No - Account locked temporarily following 3
invalid login attempts
PowerOff No UPS Output Power is turned off
TurnOffUpsStarting No PCNS has issued turn off command to the
UPS/Outlet group
ShutdownOnBattery No Relates to Advanced Configuration: the
UPS that was On Battery has started to turn off.


PCNSconfig.INI 9
Event Name Configurable in the PCNS UI?
MultipleCriticalEvent No A Critical event has occurred on more than
1 UPS in a Redundant Configuration. This causes
an OS shutdown sequence to start if the Critical
events last longer than 10 seconds.
CannotCommunicate No internal event
CannotCommunicateResolved No internal event
MonitoringStarted No internal event
ParallelSilconNotSupported
ParallelSilconSupported
No applicable to Parallel UPS Configurations
only. This event occurs if a UPS is physically
removed from the Parallel UPS Configuration.

Environmental Events
Event Name
ContactFault1
ContactFault2
ContactFault3
ContactFault4
ContactNormal1
ContactNormal2
ContactNormal3
ContactNormal4
HumidityInRangeProbe1
HumidityInRangeProbe2
HumidityOutOfRangeProbe1
HumidityOutOfRangeProbe2
TempInRangeProbe1
TempInRangeProbe2
TempOutOfRangeProbe1
TempOutOfRangeProbe2
EnvironmentCommunicationEstablished
EnvironmentCommunicationLost
EnvironmentNoCommunicationSinceLastReboot
IntegratedEnvCommunicationEstablished

5.5.1.1 Event Logging
If event logging is allowed for an event, then PowerChute Network Shutdown will expect the
following properties and values to appear in the event section.
Event Logging Properties, Values
Property Default Value Min Max Type/ Format Description
enableLogging true - - Boolean Enable event logging for this event.



PCNSconfig.INI 10
5.5.1.2 Command Execution
If command execution is allowed for an event, PowerChute Network Shutdown will expect the
following properties and values to appear in the event section.
Command Execution Properties, Values
Property Default
Value
Min Max Type/
Format
Description
enableCommandFile false - - true/false Enable execution of a command
file for this event.
commandFilePath - - String Full path to command file.
commandFileDelay 0 0 7200 Integer Delay (in seconds) before
execution of the command file.
The event must last this long,
before execution begins.
commandFileDuration 0 0 7200 Integer The amount of time (in seconds)
the command file needs to
execute.

5.5.1.3 Event Shutdown
If shutdown is allowed for an event, then PowerChute Network Shutdown will expect the following
properties and values to appear in the event section.
Event Shutdown Properties, Values
Property Default Value Min Max Type/
Format
Description
enableShutdown false - - True/False Enable OS shutdown for this
event.
shutdownDelay 120 for OnBattery
event. 0 for all other
events.
0 7200 Integer The delay (in seconds)
before this event causes
system shutdown.

5.5.2 Multiple-UPS Advanced Configuration
A special case exists for the SinglePowerFailed event. This event represents a single UPS going on
battery in a redundant UPS configuration. It is cancelled by the SinglePowerRestored event.
To use the advanced configuration for redundant UPS devices, the following properties can be used,
for this event only.
These properties are valid for the [AdvancedConfig] INI section only. If added to any other event INI
sections, validation errors will occur.
Additional Properties, Values for SinglePowerFailed event
Property Default Min Max Format Description
SinglePowerFailed_enableLogging true True/false Enable logging
for this event.


PCNSconfig.INI 11
Property Default Min Max Format Description
SinglePowerFailed_enableCommandFile Quoted
path to
command
file

SinglePowerFailed_turnOffUPS false True/false Turn off a single
failing UPS in a
multiple
configuration.
SinglePowerFailed_turnOffUPSDelay 0 0 7200 Integer Turn off a single
failing UPS in a
multiple
configuration
when the UPS
has been on
battery this long
(seconds).