scada-manager commands

This page is for support and IT staff. Everyday work is done in the interface; the command line is for tasks such as recovering the root account, taking a project over between version lines, backing up from a scheduled task or loading server scripts from a folder. Open a command prompt or PowerShell as administrator on the server.

In the interface instead

Task	In the interface
Start, stop or restart YTCC	The YTCC service in Services; see Manage the YTCC processes
See the processes, restart a driver	Processes on the home page; see Manage the YTCC processes
Start or stop a project	Start and Stop on the home page; see Start, stop and restart a project
Take a project over from another version	Stop it there and start here…; see Run lock and side-by-side versions
Back up and restore a project	Back up… and Import on the home page; see Backup and restore
Upgrade a project database	The setup program, or Upgrade… on the home page; see Databases and schema upgrade
See the version and the installed lines	Settings › About and YTCC installations on this computer; see Which version you are reading
Change the ports	Settings › Ports and Projects and ports; see Port table
Change the root password	Session button › Change password; see Root, the system administrator
Change the database password	The setup program, Repair; see Security hardening checklist
Request, load or release a licence	Licence on the home page; see Licence and Capacity Unit

Running the commands

scada-manager is the process manager of YTCC and its command-line tool. Run it in PowerShell in the installation folder, for example cd C:\ytcc\v15 and then .\scada-manager <command>. The setup program adds the installation folder to the system PATH, so there scada-manager <command> works in any command prompt. scada-manager --help and scada-manager <command> --help list the options.

Commands that change the state of a running YTCC (start <ID>, stop, restart, start-project, stop-project) read the control key from data\control.key in the installation folder. The process manager writes a new key at every start. Run these commands as a user who can read that file.

When the database password is kept in config\secrets.toml, as in an installation made with the setup program, only administrators can read it. The commands that connect to the database then need a PowerShell opened as administrator: start (whole YTCC), migrate, db-password, backup, import, script, project and the version subcommands such as version purge. status, stop, restart, start <ID>, start-project, stop-project, version, ports and license do not read the file and work in a normal window. Without the rights, the command stops with an error that secrets.toml cannot be read and that it must run as administrator.

Choosing the version line

When several YTCC version lines are installed on one computer, for example v15 (1.5.x) and v16 (1.6.x), the first word of the command chooses the line. The scada-manager command finds the installed lines in the list of installations that the setup program keeps in the Windows registry, so the result is the same in whichever installation folder or PATH entry you run it.

Command	What it does
scada-manager list	Prints a table of the installed lines: line, product version, service, control port, state and folder. The state is stopped, running without a project, or running with the name of the open project. The line you run the command in is marked with *.
scada-manager status	With several lines installed, prints the same table, then the process table of every line that runs, each under a heading with the line and its folder. When no line runs, it says that no YTCC is running. With one installation, prints the process table.
scada-manager v15 <command>	Runs the command in the v15 line, for example scada-manager v15 start or scada-manager v15 start-project pump_station.
scada-manager dev <command>	Runs the command in the development environment, a source checkout of YTCC.

With one installation, write the commands without a line, as before: scada-manager start. With several, a command without a line is not guessed: scada-manager lists the installed lines with an example and ends with exit code 2. A line that is not installed ends the same way.

start, stop and restart without a line are the exception:

• stop and restart go to the running line without asking when only one line runs.
• Typed in a command prompt, they ask which line to use. The list shows each line with its version and folder, marks the line that ran last and the line that runs now with its project, and the default is the line that ran last (Enter). Type the number or the line name, for example v16; q cancels with exit code 1. An invalid answer asks again.
• For start, choosing the line that already runs only says so. Choosing another line while one runs asks for confirmation, because only one project runs on the computer: answering e stops the running line, waits until it has stopped (at most 60 seconds) and then starts the chosen one; Enter or h cancels.
• Called from a script, a service or the setup program, no question is asked: the lines are listed and the command ends with exit code 2, so scripts must name the line.

The line that ran last is read from data\manager-state.json of each line.

Global options

Give these before the command, for example .\scada-manager --port 5001 status.

Option	Default	Meaning
--root <folder>	.	Installation folder that relative paths refer to. In a version folder the version folder is used.
--config <file>	config/manager.toml	Process manager configuration.
--ports <file>	config/ports.toml	Port table.
--port <port>	from ports.toml (manager)	Control port of the process manager.
--help, -h		Shows the help.
--version, -V		Shows the program version.

Processes

Command	What it does	Needs
start	Starts all YTCC processes in the background and returns. If YTCC already runs in this folder, it says so and does nothing.
start <ID>	Starts one process. <ID> is the ID column of status.	Running YTCC, control key
stop	Stops all processes and the process manager.	Running YTCC, control key
stop <ID>	Stops one process.	Running YTCC, control key
restart <ID>	Restarts one process.	Running YTCC, control key
status	Prints the process table, and a last line with the licence state.	Running YTCC

Options of start (whole YTCC only):

Option	Meaning
--foreground, -f	Runs in the foreground until Ctrl+C instead of returning; for an external service manager.
--no-open	Does not open the interface in the browser after the start.
--strict	Refuses to start with a weak PostgreSQL password, as weak_db_password = "deny" in manager.toml does.

See Manage the YTCC processes.

Projects

Command	What it does	Needs
start-project <project>	Starts the drivers and services of a project. Refused while another project runs on this computer, in any version line.	Running YTCC, control key
stop-project <project>	Stops the drivers and services of a project.	Running YTCC, control key

<project> is the part after scada_proj_ in the project database name, for example pump_station for scada_proj_pump_station, or for scada_v15_proj_pump_station in the v15 line.

Options of start-project:

Option	Default	Meaning
--takeover		If the same project runs in another YTCC version, asks that version to stop it, then starts it here.
--wait-secs <s>	15	Seconds to wait for the other version to stop.

start-project also refuses when a port that a driver of the project listens on is used by another program or another YTCC installation. Nothing of the project is started, and the port is not changed by itself. See Run lock and side-by-side versions.

Database upgrade

Command	What it does
migrate <project>	Upgrades the project database to the schema of the installed programs. Refuses while the project's drivers run.
migrate --registry	Upgrades the registry. Refuses while any YTCC process runs.
migrate --all	Upgrades the registry and then every project that is not archived. Refuses while any YTCC process runs. Each project is backed up first; a project whose backup fails is not touched. The command ends with a non-zero exit code if any project was not upgraded.

--backup-dir <folder> sets the folder of the backups of migrate --all. The default is backups\exports in the data folder.

See Databases and schema upgrade.

Database password

db-password changes the password of the PostgreSQL role in one step. It sets the password in PostgreSQL, checks that the new password can sign in, and then updates the settings: pg_password in config\secrets.toml, otherwise the postgres:// addresses in config\*.toml. If a step fails, the old password is restored. YTCC must be stopped; otherwise the command ends with The stack is running. Stop it first: scada-manager stop.

Option	Meaning
--password <password>	The new password, instead of asking. It stays in the shell history; prefer to type it when asked.
--generate	Generates a strong password of 24 characters and prints it once, before anything changes. Store it safely. Cannot be combined with --password.
--force	Accepts a weak password.

Without --password or --generate, the command asks for the password twice without showing it. The password must have at least 12 characters, must not be a known weak password and must not be the user name. Start YTCC afterwards with scada-manager start.

Licence

Command	What it does
license status	Shows the licence file, its signature, the machine identity match per item, the clock and the day counts, and the usage while YTCC runs. --json prints the same as JSON.
license request --customer <name> --site <name>	Writes a request file. Add --accept-eula to accept the licence agreement; without it, the command prints the agreement digest and where to read it, and writes nothing.
license activate <file>	Verifies a licence file and installs it. A running YTCC uses it immediately.
license release	Writes a signed receipt and removes the licence from this server. YTCC keeps running. Asks for confirmation; --yes skips the question.
license usage-report	Writes the signed usage report. Needs a running YTCC.
license inspect <file>	Shows the type, signature and contents of a .ytreq, .ytlic, .ytrel or usage report file. Changes nothing.

Option	Applies to	Meaning
--cu <n>	request	The CU you need. Required while YTCC is stopped, because the usage cannot be measured then.
--out <file or folder>	request, release, usage-report	Where to write the file. The default is config\license, with the names <server name>.ytreq, <licence no.>.ytrel and <server name>-usage.txt. An existing file is never overwritten.

While YTCC runs, request, activate, release and usage-report go through the running licence service and read the control key from data\control.key. Run them as the account that started YTCC or an administrator. Otherwise they change nothing and say so; use the Licence tab, or stop YTCC and run the command again.

Exit code	Meaning
0	Success.
1	The command failed; the message gives the reason and the fix.
2	A condition was not met: the agreement was not accepted or the confirmation was not given.
3	The licence service is needed but not running, or the command could not be authorised.

See Licence and Capacity Unit.

Backup and import

backup <project> writes a full backup of one project to one zip file. It works while the project runs. <project> can be the slug, the project ID (scada_proj_<slug>) or the display name. The default file is backups\<project>-<version>-<date>-<time>.zip. The home page takes the same backup with Back up…; see Back up a project from the home page.

Option	Meaning
--out <file or folder>	Writes to this file, or with the default name into this folder.
--force	Overwrites an existing --out file.
--skip-unreadable	Finishes the backup even if some content cannot be read; the skipped items are listed. Without it, the backup is refused.
--sample	Makes a sample package without users, password hashes, audit log and the project's old backups.
--data-dir <folder>	Data folder of the projects server. Default: SCADA_DATA_DIR or apps\projects-server\data.

import <file>.zip restores a backup as a project. YTCC must be stopped. During a design lock only a restore under the same identity works: --name and --new-identity are refused, --cleanup still works.

Option	Meaning
--name <name>	Imports under a new name (new ID, folder and database). Needed when the name is taken; the command does not choose a name by itself.
--new-identity	Imports as a separate project with a new identity. Needed when the same project exists here under another name.
--cleanup <project>	Instead of importing, removes the leftovers of an interrupted import of <project>. Never removes an active project.
--data-dir <folder>	Data folder of the projects server, as for backup.

See Backup and restore.

Server account

server-user recovers the root account, the system administrator of the server. It works only on the files in the data folder of the projects server, so it runs while YTCC runs or when it is stopped, and needs no restart afterwards.

Command	What it does
server-user reset	Sets a new password for the account root. Asks for it twice without showing it. Also unlocks the account, clears the failed attempts, enables the account, ends its open sessions and writes the reset to the audit log of the server account. If the server has no server account at all, creates one.
server-user list	Lists the server accounts: user name, enabled, locked and the time of the last password change. Never shows password hashes.

Options of server-user reset:

Option	Default	Meaning
--user <name>	root	The account to reset. If the name does not exist, the command lists the existing names and stops.
--password <password>		The new password, instead of asking. It stays in the shell history; prefer to type it when asked.
--data-dir <folder>		Data folder of the projects server. Default: SCADA_DATA_DIR or apps\projects-server\data.

list takes --data-dir as well. A password that breaks the rule of the root password (at least 12 characters, an uppercase letter, a lowercase letter and a digit, not containing the user name) is accepted with a warning. See Recover the root account.

Server scripts

Command	What it does
script import <project> <file or folder>	Loads .js files into the server scripts of the project.
script export <project> <folder>	Writes the server scripts of the project to a folder: <name>.js, or <name>.ts for a script written in TypeScript in the editor.
script sync <project> <folder>	Loads the changed .js files of a folder written by script export. A script changed in the editor since the export is not overwritten; the conflict is reported.

Options of script import: --activate, --can-command with --targets <patterns>, --can-publish with --publish-targets <patterns> or --publish-targets-file <file>, --handler-ms <ms> (10 to 60000) and --dry-run. Option of script export: --force replaces the existing .js and .ts files and removes the files of scripts that are no longer in the project; without it the folder must contain no .js or .ts file. Options of script sync: --watch keeps running and loads every saved file until Ctrl+C, and --activate also activates the loaded scripts. During a design lock, script import works only with --dry-run and script sync is refused. See Import and export server scripts.

Versions and ports

These commands do not need a running YTCC, except project reclaim.

Command	What it does
version	Prints the product version, the installation ID and the contract versions.
version --json	The same as JSON, with the database names of every project (slug, db_name, hist_db_name).
version purge <ID> --confirm <ID>	Deletes another installed version under the same root: its project and history databases, its registry and its folder.
ports suggest	Prints a free port block for this version. It takes into account the versions under the same root and the version lines installed with the setup program.
ports suggest --project <project>	Prints a free port set (nats, gateway, alarm) for a project that runs with its own message bus and gateway.
project adopt <project>	Takes a project over from another installed version.
project reclaim <project>	Takes a project back from the version it was adopted into. Needs this version running.

Options of version purge:

Option	Meaning
--confirm <ID>	Required; must repeat the installation ID.
--yes	Skips typing the ID again (for scripts).
--include-chained-history	Deletes the databases that no history chain uses. History databases that another version still reads are never deleted.

Options of ports suggest:

Option	Meaning
--write	Writes the block to config\ports.toml, or to config\ports.toml.suggested if ports.toml exists. With --project, records the ports in this version's config\projects.toml.
--project <project>	Suggests the ports of the project instead of a version block.

Options of project adopt:

Option	Meaning
--from <ID>	Source version folder under the same root, for example v12.
--from-root <folder>	Source standalone installation folder, instead of --from.
--takeover	If the project runs in the source, asks it to stop.
--replace	If the project already exists here, renames the existing copy and continues.

Options of project reclaim:

Option	Default	Meaning
--yes		Does not ask for confirmation (for scripts).
--wait-secs <s>	15	Seconds to wait for the other version to stop.

See Install versions side by side and Upgrade to a new version and roll back.

Settings files

A few settings of the installation have no field in the interface. They are in the config folder of the installation, which only administrators can change; open the file in a text editor started as administrator and restart the YTCC service afterwards. An upgrade keeps these files.

Setting	File	Default	Effect
backup_exports_keep	manager.toml	10	How many home-page backups per project are kept in backups\exports, from 1 to 1000.
weak_db_password = "deny"	manager.toml	warn	Refuses to start with a weak PostgreSQL password instead of warning. start --strict does the same once.
log_days	log.toml	10	Days the log files are kept; 0 keeps every file. See Logs and diagnostics.
run_lock_grace_secs	manager.toml	30	Seconds the process manager tries to take a lost run lock back. See Run lock.
legacy_control_ports	manager.toml	none	Control ports of YTCC v1.5.0 or older on the same server, for the run-lock check.
nats_bind	manager.toml	127.0.0.1	Address of the message bus. Leave it unset; see Security hardening checklist.
SCADA_PG_POOL_MAX	manager.toml, under [process.inject] of a process	2 or 6	Largest PostgreSQL connection pool of that process, from 1 to 64. See Connections to PostgreSQL.
[access]	gateway.toml	none	Client addresses the live data server accepts; see Security hardening checklist.
Last-value store	gateway.toml	on	See Persistent last-value store.
YTCC_IMPORT_MAX_MB	Environment of the projects server	2048	Largest project package that the home page imports, in MB.

Command-line output

The commands print short lines without colors or time stamps. By default only warnings and errors are shown; the details go to the log file in logs. For more output, set the environment variable RUST_LOG, for example $env:RUST_LOG = "info".