Configuration Through CLI Utility
The command line interface (CLI) version of configuration provides the same configuration functionality as the property dialogs in PSQL Control Center. The CLI Configuration runs on the Windows, Linux, and OS X platforms supported by PSQL v12.
On Windows, the executable program is bcfg.bat and is installed, by default, in the Program Files directory.
On Linux and OS X, the executable program name is bcfg and is located, by default, in the /usr/local/psql/bin directory. The following requirements must be met to run bcfg on these two systems.
Table 6
Requirements for Running bcfg
Requirement
Discussion
Java Runtime Environment (JRE)
The JRE components required to run bcfg are installed as part of PSQL. Bcfg uses the local version of the JRE installed as part of PSQL.
PSQL server or client
A compatible PSQL server or client must already be installed on the same machine. See Installing PSQL Server, Vx Server, and Client for Linux and OS X in Getting Started with PSQL.
If you have met the requirements to run bcfg and still are having difficulty running the utility, see the following troubleshooting guide.
Table 7
Troubleshooting Guide for Running bcfg
Troubleshooting Condition
Discussion
You receive the error “java.lang.UnsatisfiedLinkError."
This error typically occurs if you try to start bcfg by double-clicking the script file using a file browser application. Start bcfg from a command prompt.
This error can result if the LD_LIBRARY_PATH variable is not set. If you run bcfg as user psql, this variable is set in the profile for psql. You may also explicitly set the variable with the following command:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/psql/lib64
On OS X, the variable is DYLD_LIBRARY_PATH.
You receive the following error message:
"Unable to connect to database engine. Make sure the target machine is accessible and an engine is running on the target machine.”
The context of this error occurs if you attempt to administer the local server.
To administer the local server, you must be a member of the pvsw group or be the root user.
See also PSQL Account Management on Linux and OS X in Getting Started with PSQL.
Setting a Configuration
You can configure settings one at a time from the command line or by providing one or more settings in an input file.
*Tip: A convenient way to create an input file is first to create an output file. You can then edit the output file and use the edited version as an input file. See Editing an Input File for the types of edits permissible.
Restarting the Engines
If you use an input file, bcfg prompts you to restart the database engines after the utility processes the file. The restart applies regardless of the settings in the input file. Stopping then starting the engines ensures that the configuration settings take effect.
If you configure a setting from the command line, bcfg prompts you to restart the database engines only if the setting requires a restart.
See Ensuring Configuration Changes Take Effect for how to restart the engines.
Example Scenario: Configuring a Single Setting from the Command Line
Suppose that you want to turn on a configuration setting having to do with reconnecting a client to the server in the event of a network outage. You are not certain about the name of the configuration setting. Complete the following steps.
1
At a command prompt, type bcfg -H reconnect then press Enter.
The utility reports all settings that contain the string reconnect:
ID               Setting Name
-----------------------------
29               Enable Auto Reconnect
148              Enable Auto Reconnect
149              Auto Reconnect Timeout
Two of the settings, 29 and 148, look like what you want, but which is which?
2
Type bcfg 29 then press Enter.
The utility reports the following for setting ID 29:
=====================
ENABLE AUTO RECONNECT
=====================
ID: 29
Value: Off
Options: On     Off
Default Value: Off
Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.
The description tells you that this setting applies to a client and that the setting is currently off.
3
Type bcfg 29 on then press Enter.
The utility informs you that system setting 29 has been updated.
4
If you want to verify that the setting is now on, type bcfg 29 then press Enter.
The utility reports the following for setting ID 29:
=====================
ENABLE AUTO RECONNECT
=====================
ID: 29
Value: On
Options: On    Off
Default Value: Off
Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.
Note that the value is now set to on.
Editing an Input File
An input file must contain at least one complete record for one setting. If you create an input file from an output file and want to remove configuration settings, ensure that the remaining settings are complete records.
At a minimum, a complete record encompasses an ID and Value pair. However, to ensure clarity, it is recommended that you include the top line of the setting header through the setting’s description. For example, here is a suggested minimal record for Enable Auto Reconnect:
=====================
ENABLE AUTO RECONNECT
=====================
ID: 29
Value: On
Options: On    Off
Default Value: Off
Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.
Other than limiting which setting records are included in the input file, the only other change allowed is to the Value assignments. The assignment can be whatever is specified by Options or by Range.
Command Syntax
bcfg -I inputfile [-S server] [-U username]
[-P password] [-E]
or
bcfg -O outputfile [-S server] [-U username]
[-P password] [-E]
or
bcfg ID [value] [-S server] [-U username]
[-P password]
or
bcfg -H <keyword | ''keyword with spaces''> [-S server]
[-U username] [-P password]
Options
-I
Required parameter if you provide an input file to the utility.
inputfile
A text file that contains one or more configuration setting records for a specified server and the value assigned to each setting.
A convenient way to create an input file is first to create an output file. You can then edit the setting values as required and use the edited version as an input file. See Editing an Input File for the types of edits permissible.
-O
Required parameter if you want the output results of running the utility sent to a text file.
outputfile
A text file that contains the current configuration settings for a specified server as a result of running the utility.
ID
A two or three digit integer that uniquely identifies the configuration setting.
Some configuration settings require that you restart the database engines for the setting to take effect. Bcfg prompts you if a restart is required. See Restarting the Engines.
value
A value assigned to the configuration setting. The valid values are specified in a setting record in Options or Range.
If Value is omitted, the utility returns the current setting.
If Value is included, the utility changes the setting based on the value assignment.
See Example Scenario: Configuring a Single Setting from the Command Line.
-H
The help search option for a keyword (that is, help for a keyword). The utility searches for configuration settings that contain keyword and returns the ID and setting name, or returns “no matches found.” See also next row in this table.
keyword
The name of the configuration setting, such as ALLOW CLIENT-STORED CREDENTIALS or SUPPORTED PROTOCOLS.
Note that keyword is case insensitive. However, if the keyword contains one or more spaces, you must double quote the string.
The utility can provide help based on partial keywords. For example, if you specify -H client, the utility returns all setting with the word “client” as part of the setting name. If you specify -H a, the utility returns all settings with an “a” in the name.
-S
Required parameter if the configuration settings apply to a remote server (a server other than the local one).
server
The name or IP address of the remote server that contains the database engine.
-U
Required parameter if a user name is required to access server.
username
User name with which you will connect to server. See also PSQL Security.
If server is a local machine, the username and password are not required if:
•
You are logged in to the local machine as an administrator or as a member of the Pervasive_Admin group
•
The local machine is not running Terminal Services.
-P
Required parameter if a password is required to access server.
password
Password used with username to connect to the server. See username. See also PSQL Security.
-E
Ignore errors when reading inputfile or writing to outputfile.