The commands LoadFirmware, LoadConfig, LoadScript and LoadFile

Inserted or changed with LCOS 8.50

Various applications, such as loading configurations, firmware versions, scripts, and verifying server identity with certificates, require files to be stored to a device. You can to upload these files to a device with LANconfig or WEBconfig. Alternatively, you can use Telnet or SSH to issue a command from the command line to download the files directly from a server (TFTP, HTTP or HTTPS) and into the device. This process simplifies device administration in larger installations that rely on regular updates to the firmware and/or configurations.

The following commands are used to upload different file types to the device:

LoadConfig: Uploads a configuration file (with file extension *.lcf) into the device.
LoadFirmware: Uploads a firmware file (with file extension *.upx) into the device.
LoadScript: Uploads a script (file extension *.lcs) to the device, e.g. for partial configurations.
LoadFile: Uploads various types of file to the device.

The following descriptions use 'LoadCommand' to describe the upload commands in general.

The upload commands can use the protocols TFTP, HTTP and HTTPS to upload the selected file. A TFTP server is identical to an FTP server in terms of functionality, but uses a different protocol for data transmission. When using an HTTPS server, a certificate used to check the identity of the server can be stored on the device.

Anmerkung: The LoadFile command in LCOS version 8.50 supports the protocols HTTP and HTTPS only.

The load commands are invoked from the command line interface with the following syntax:

LoadCommand <parameters>

The parameters are used to control the behavior of the commands. The parameters can be used in any combination. The only requirement is for a URL to be specified.

Values for condition, URL, or minimum version entered at the command line overwrite (once only) the values set under /Setup/Autoload/Network. Conversely, the values defined in the setup act to supplement the command-line commands if no parameters are entered manually.

General parameters for the load commands:

-a: This parameter defines the sender address that the device sends to the server when downloading a file. Enter the sender address in one of the following forms:
- Any valid IP address
- INT for the address of the first intranet
- DMZ for the address of the first DMZ
- LB0 to LBF for the 16 loopback addresses
  Anmerkung: If the list of IP networks or loopback addresses contains an entry named 'DMZ' then the associated IP address will be used.
<URL>: This parameter specifies the the URL for downloading a file from a TFTP or HTTP(S) server. Enter the URL in the following form:
```
LoadCommand protocol://Server/Directory/Filename.ext
```
For password-protected file access, enter the data in the following form:
```
LoadCommand protocol://username:password@Server/Directory/Filename.ext
```
-s: When downloading a file from a TFTP server, this parameter specifies its DNS name or IP address. Use this syntax as an alternative to specifying a URL.
-f: When downloading a file from a TFTP server, this parameter specifies the name of the required file. Use this syntax as an alternative to specifying a URL.

If the parameters <URL> or -s and -f are not specified, the device executes the commands LoadFirmware, LoadConfig or LoadScript with the default values for the URL as defined under /Setup/Autoload/:

Use these default values if the latest configurations, scripts and firmware versions are always stored under the same name in the same location. If this is the case, the commands LoadConfig, LoadFirmware and LoadScript can be used very easily to load the relevant files automatically.

The following parameters are of particular importance for automatic uploading:

-Cn: This parameter checks if the file referenced by the LoadFirmware command is newer than the firmware on the device.

-Cd: This parameter checks if the file referenced by the LoadFirmware, LoadConfig or LoadScript command is different to the firmware or configuration on the device, or newer than the last executed script. When the LoadScript command is used, this parameter updates the checksum stored in the device for the most recently executed script.
-u: This parameter disables the version checking. The file referenced by the LoadFirmware, LoadConfig or LoadScript command is uploaded and executed unconditionally. When the LoadScript command is used, this parameter does not change the checksum stored in the device for the most recently executed script.
-m: This value defines the minimum version of the firmware. The firmware referenced by the command must be at least of this version in order for the command LoadFirmware to execute.

Anmerkung: The default setting for the conditions under /Setup/Autoload/Network are "Unconditionally". In the default setting, no version checking is carried out when the commands LoadFirmware and LoadConfig upload firmware, or when LoadScript executes a script file.

Anmerkung: The parameter -u always has priority over other parameters entered in a command.

When transferring files from an HTTPS server to a client device, the network components check the identity of the remote site by using certificates. For the automatic loading from HTTPS servers, additional parameters are available for downloading and subsequently checking the certificates:

-o <Path/Filename.ext>: This parameter specifies the destination when downloading a file from an HTTP(S) server with the LoadFile command. For example, you can use this option to save a certificate on your device for future identity verification when accessing an HTTPS server.
-c <Path/Filename.ext>: This parameter specifies the name of the certificate used by the device to check the identity of an HTTPS server when downloading a file.
-p <Path/Filename.ext>: When downloading a file from an HTTPS server, this parameter specifies the name of the PKCS#12 container. The PKCS#12 container can contain multiple CA certificates, and thus supports the identity checking of HTTPS servers with certificate chains. A PKCS#12 container can additionally contain a device certificate and the corresponding private key, so that it can confirm the identity of the device to the HTTPS server if this server requires authentication by certificate.
-d: The device uses this passphrase to encrypt an unencrypted PKCS#12 container.
-n: This parameter disables the server-name check when downloading a file from an HTTPS server using the LoadFile command. If you use the download URL to specify the server as a DNS name (and not as an IP address), then the device additionally communicates the server name when sending its request to the server. If the HTTPS server is a virtual server, then this server can respond with the appropriate certificates for the reported DNS name. Without this parameter, the device checks whether the DNS name in the download URL agrees with the common name of the submitted certificates. The unit will start the download only if this check is successful.

Use one of the two following notations to specify a file in the file system of the device:

Specify a location in the device's internal file system with the path '/minifs/filename.ext'.
Specify a location on an external USB data medium with the path '/mountpoint/directory/filename.ext'. The available mount points are listed under '/status/file-system/volumes'.

In file names that include the path, you can use the following general variables:

%m: The LAN MAC address of the device (hexadecimal, lowercase letters, no separators)
%s: The device serial number.
%n: The device name
%l: The location of the device ('location' – from the configuration)
%d: The device type

Anmerkung: You can use these variables in the load commands, but you cannot change the values for the variables.

In addition to these general variables, you can also use the following environment variables that relate to the device for more flexibility when executing the load commands. All predefined environment variables begin with two underscores: When entering commands on the command line, the variables are preceded by a dollar sign.

__BLDDEVICE: The sub-project of the device. This environment variable stands for the second part of the value for PROJECT if you execute the command #sysinfo# from the command line. The sub-project generally consists of a string without spaces and it stands for the hardware model of the current device.
__DEVICE: The type of the device, for example as displayed in LANconfig or on the device type label.
__FWBUILD: The build number of the firmware currently used in the device. The build number is a number
__FWVERSION: The version number of the firmware currently used in the device, in the form 'x.yy'. The firmware version consists of the major release before the dot and the minor release after it.
__LDRBUILD: The build number of the firmware currently operating in the device. The build number is a four-digit number.
Anmerkung: When requested for the loader build number, older loaders return an empty string.
__LDRVERSION: The version number of the loader currently installed in the device, in the form 'x.yy'. The loader version consists of the major release before the dot and the minor release after it.
__MACADDRESS: The type of the device, given as a 12-digit string of hexadecimal values with lowercase letters and no separators.
__SERIALNO: The device serial number.
__SYSNAME: The system name of the device.

Anmerkung: If you have already used a name from the environment variables as a user-defined variable in a section of the configuration, then both the configuration and the commands on the command line work primarily with the values of the user-defined variables.

Use the following commands in the CLI to display or modify the environment variables:

printenv: Displays all environment variables and their current values. If you have set one or more environment variables with the command setenv, the output of the command printenv shows the user-defined value at the top and the default value below it.
echo __device: Displays the current values of a single environment variable, in this example the value for the variable '__DEVICE'.
setenv __device MeinWert: Sets the value of an environment variable to the desired value.
unsetenv __device: Sets the value of an environment variable to the default value.

Examples of load commands:

With the following Telnet command, the device loads a firmware file named 'LC-1811-5.00.0019.upx' into the device from directory 'LCOS/850' on the TFTP server with IP address '192.168.2.200':
```
LoadFirmware -s 192.168.2.200 -f LCOS/850/LC-1811-8.50.0019.upx
```

With the following Telnet command, the device loads a script intended for a certain MAC-address (named, for example, '00a0571735da.lcs') from the TFTP server with IP address '192.168.2.200':
```
LoadScript -s 192.168.2.200 -f %m.lcs
```
With the following Telnet command, the device loads a firmware file named 'LC-1811-5.00.0019.upx' into the device from directory 'download' on the HTTP server 'www.myserver.com'. At the same time the identity of the server is checked with the certificate 'sslroot.crt':
```
LoadFirmware -c sslroot.crt https://www.myserver.com/download/LC-1811-8.50.0019.upx
```
With the following Telnet command, the device loads a script intended for the specified serial number and the current firmware. The device reads the values for serial number and firmware from the corresponding environment variables:
```
Loadscript $__SERIALNO-$__FWVERSION.lcs
```