7.3.3. Start and management of a standalone server

7.3.3.1. General information

The standalone server and the server management utility are started from the command line. Specify all the required parameters in the standalone server configuration file or startup command line. Information about performing a specific action is output to a standard output stream (stdout). If successful, the return code is equal to 0. Otherwise, the return code is non-zero and an error message will be sent to the standard error stream (stderr).

Both the standalone server (ibsrv) and the server management utility (ibcmd) contain a built-in help system. The documentation does not contain a detailed description for all commands of the startup command line. It contains only typical cases of use.

To get a reference information, use the following option to run utilities:

ibsrv help
ibcmd help

If you need to get a description of the selected server management utility mode (the example contains the help for the server mode), use the following command:

ibcmd help server

You can save the help for further use via operating system tools for standard output stream redirection:

ibcmd help server > .\server.desc

When a standalone server (ibsrv) is running, connection to the database is implemented in a shared mode.

7.3.3.2. Standalone server start

A standalone server can be started as a regular operating system application, as well as an operating system service (for Windows OS) or in daemon mode (for Linux OS).

A standalone server does not provide built-in tools for registering itself as a service of the operating system. Management tools (start and stop) are also not provided by the service. For these operations, you should use the operating system tools (sc utility).

The standalone server configuration file is used to specify standalone server instance parameters. The configuration file is used both by the server and administration utility. You can specify certain server parameters using the command line (both of the server and management utility) or a configuration file. The last option allows you to manage all the standalone server parameters except for location paths of standalone server service directories (see article Specify the location of the standalone server service directories). The standalone server configuration file does not have a default location. So, each time you start the standalone server (or management utility), you must explicitly specify the file location. The standalone server configuration file is generated in YAML format. For the file description, see article Standalone server configuration file.

When starting a standalone server, do not forget about following features:

When starting a standalone server, the parameters necessary for its operation are defined as follows:
- The values of all parameters specified in the startup command line are received.
- An attempt to get values of the remaining parameters using the server configuration file is made.
- If you cannot get the values of the remaining parameters using the server configuration file, the default values are used.
- The parameter values specified in the startup command line have priority over the values from the configuration file.
Create a server configuration file using a special command (ibcmd server config init) or manually.
Either one standalone server instance or one server management utility can operate with the same data directory at the same time. Specify a data directory (the --data parameter) for simultaneous operation of several standalone server copies or for almost any operation with the standalone server.
Only one application from the following list can operate with the same database at the same time:
- Standalone server.
- Standalone server management utility (in offline mode).
- 1C:Enterprise server cluster.
- Client applications running in the file mode upon direct connection (not via a standalone server).

When describing the start command line, it is assumed that the start is executed from the bin directory of the required version of the 1C:Enterprise system.

Application start, file option

Start a standalone server to use a file infobase. The infobase data directory is located in c:\db\standalone-server\demo. All parameters of the standalone server in this case will be set to the default values.

ibsrv --data="c:\db\standalone-server\demo"

The infobase file (1Cv8.1CD) is located in the following directory: c:\db\standalone-server\demo\db-data.

If you start the standalone server with absolutely no parameters, the standalone server will attempt to start with file mode of the infobase, which is located in the default data directory.

Application start, client-server mode

The standalone server is started to operate with client/server mode of the infobase, which has the following parameters:

Microsoft SQL Server DBMS is used.
To access the DBMS, the dbUser user with the dbUserPassword password will be used.
The database name in DBMS is dbName.
It is assumed that the database exists and is truly a 1C:Enterprise database.

ibsrv --dbms=mssqlserver --db-server=dbServerName --db-user=dbUser --db-pwd=dbUserPassword --db-name=dbName --data="D:\ss-data\dbName-data"

If both parameters (--db-path and --dbms) are not specified when starting the standalone server, then the standalone server will be started with the file infobase, which is located in the following directory:

Windows: %LOCALAPPDATA%\1C\1cv8\standalone-server\db-data.
Linux: ~/.1cv8/standalone-server/db-data.

Server registration service (Windows OS)

In order to register a standalone server as a Windows OS service, you can use the following command file (or take it as a basis for further upgrades).

@echo off
rem %1 – 1C:Enterprise full version
rem %2 - instance number of the registered service
rem %3 - server configuration file location
rem %4 - infobase data directory
set SrvcUserName=<standalone server user>
set SrvcUserPwd=<password of the standalone server user >
set SrvcName="Standalone server %2"
set BinPath="\"C:\Program Files\1cv8\%1\bin\ibsrv.exe\" --service --config=\"%~3\"" --data=\"%~4\""
set Desctiption="1C:Enterprise 8.3 standalone server. Copy #%2. Directory %4
sc stop %SrvcName%
sc delete %SrvcName%
sc create %SrvcName% binPath= %BinPath% start= auto obj= %SrvcUserName% password= %SrvcUserPwd% displayname= %Desctiption%

When starting this command file, the following parameters are used:

The full number of 1C:Enterprise version from which a standalone server will be used.
The instance number of the service to register. In the above example, the existence of a service with the given number is not checked. Due to the fact that the standalone server serves one database, with this parameter you can register your OS service for each served infobase.
The full path to the configuration file for this instance of the standalone server (must be enclosed in double quotes). This configuration file must contain all parameters used to start the standalone server, including database parameters. Different service instances must have their own configuration files.
The full path to the infobase data directory. This directory contains infobase service data: an event log, a full-text search index, a temporary directory, and so on.

Example of starting the command file (administrator rights are required):

register-ss.bat 8.3.20.100 2 "d:\1C DB\standalone-server\demo\demoma.yml" "d:\ss-data\demoma"

After starting the command file with these parameters, the following actions will be executed:

Service name: Standalone server 2.
Displayed name: 1C:Enterprise 8.3 standalone server. Copy #2. Directory d:\ss-data\demoma.
1C:Enterprise version: 8.3.20.100.
Service startup command line: "C:\Program Files\1cv8\8.3.20.100\bin\ibsrv.exe" --service --config="d:\1C DB\standalone-server\demo\demoma.yml" --data="d:\ss-data\demoma".
Service start mode: Automatic.

In this case, the following operating system commands should be used to manage the service:

Start service: sc start "Standalone server 2"
Stop service: sc stop "Standalone server 2"
Delete service: sc delete "Standalone server 2"

By the time the service starts, the configuration file must contain all the necessary parameters for starting the standalone server.

Server start in daemon mode (Linux OS)

To start a standalone server in daemon mode on Linux OS, execute the following command:

ibsrv --daemon --config="configuration file path" --data="data directory path"

By the time the standalone server starts in daemon mode, the configuration file must contain all parameters required to start the standalone server.

7.3.3.3. Standalone server management

7.3.3.3.1. General information

As mentioned above (see article Standalone server start), you can specify standalone server parameters using the configuration file or startup command line. You can specify a certain standalone server instance using the following methods:

The --data command-line parameter of the ibcmd utility. In this case, the management utility performs actions with the infobase that is described by the data directory specified in the --data parameter. This management mode can be referred to as offline mode since you do not need a standalone server instance to execute commands. If a standalone server instance runs with a data directory, offline management mode is unavailable.
The --pid or -p command-line parameters of the ibcmd management utility. In this case, the management utility connects to a standalone server instance running on the same computer as the ibcmd utility. The --pid parameter value is an operating system process number of the running standalone server instance. The process number is specified in values of the operating system where the standalone server is running.
For example: --pid 16453.
The --remote or -r command-line parameters of the ibcmd management utility. In this case, the management utility connects to a standalone server instance running on a remote computer. The standalone server running on a remote computer must be configured so that it provides access to the infobase and the server over SSH protocol. The standalone server instance is identified using a URL and a port that hosts the standalone server.
For example: ssh://server1C:8282.

You do not need to specify the --data parameter or other parameters describing the infobase access parameters if a "remote" server is administered. The standalone server already contains all the required information. It is specified in the configuration file or ibsrv startup command-line parameters. In this case, "remote" means administration of any running standalone server instance using the --pid/-p or --remote/-r parameters.

When you use a "remote" standalone server, not all the management utility commands are available. Unavailable commands are listed below in the respective sections.

When you use the standalone server, an infobase session is created to perform commands that use access to the infobase. The user on whose behalf the session is created must have access rights to perform an action that is initiated by the command to be performed. If a command sent to the standalone server does not require access to the infobase but requires full access to the server (for example, to receive the session list), this command must be performed on behalf of the user with administration rights in the infobase that is serviced by this standalone server instance. Authentication is performed either interactively or using command-line options:

Specify a username: --user/-u.

Specify a user password: --password/-P.

The standalone server is administered with a restriction. If a directory is specified as a data directory of the running standalone server instance (the --data parameter), this directory cannot be used in the following cases:

When starting another standalone server instance.
When the administration utility operates in offline mode.

The order of session creation and authentication:

If access is provided via a remote connection (SSH), a session is created on behalf of the user who is authenticated in SSH gateway.
If access is provided via a local connection (a standalone server instance is selected on a local computer) or a configuration file is being configured, a session is created on behalf of 1C:Enterprise user with full administration rights.

7.3.3.3.2. Offline mode

The standalone server can perform all management utility commands. It can operate only on the same computer as the infobase data directory. The standalone server and the management utility cannot use the same infobase data directory (the --data parameter).

7.3.3.3.3. Connecting to a standalone server instance on a local computer

When you manage the standalone server using the management utility, you can use all the utility commands, except for the ones used to:

Initialize the standalone server configuration (all config commands).
Create an infobase (the ibcmd infobase create command).
Restore infobase integrity (the ibcmd infobase repair command).

7.3.3.3.4. Connect to a standalone server instance over SSH protocol

When you manage the standalone server using the management utility, you can use all the utility commands, except for the ones used to:

Initialize the standalone server configuration (all config commands).
Create an infobase (the ibcmd infobase create command).
Restore infobase integrity (the ibcmd infobase repair command).

If the standalone server supports SSH, it starts operating similarly to Designer running in agent mode. In this mode, you can connect to the standalone server (except the ibcmd utility) using third-party SSH and SFTP clients and perform certain commands. Commands that you can perform using SSH client are similar to Designer commands in agent mode but only the following commands are supported:

help. Display help information for commands. For more information, see article help.
common. Common commands. For more information, see article Common group commands.
- connect-ib. Connect to an infobase.
- disconnect-ib. Disconnect from an infobase.
options. Configure the current session. For more information, see article Options group commands.
- get. Get a parameter value.
- list. Get a parameter list.
- set. Set a parameter value.
config. Configuration editing commands (for more information, see article The commands of a group config):
- dump-cfg. Save a configuration to a file.
- dump-config-to-files. Dump a configuration to XML files.
- extensions. Operate with configuration extensions.
- generation-id. Get a generation ID for metadata.
- load-cfg. Load a configuration from a file.
- load-config-from-files. Load a configuration from XML files.
- manage-cfg-support. Disable configuration support.
- update-db-cfg. Update a database configuration.
infobase-tools. Get service information about an infobase (for more information, see article Infobase-tools group commands):
- data-separation-common-attributes-list. Get a list of common attribute names.
- debug-info. Get information about the debugger.
- dump-ib. Dump an infobase to a file.
- erase-data. Delete infobase data.
- restore-ib. Restore a configuration from a file.

Files and directories created using SFTP are placed in the user data directory.