The {{datatype}} which can be used to fetch the signature for this Deployment Unit.
The {{datatype}} may use the "data" scheme defined in
{{bibref|RFC2397}} in order to incorporate the signature into the
command directly.
Several signature formats are in common use; the device may deduce the
format used from the Content-Type of the retrieved object and/or by
examining its content.
The URL MUST NOT include the "userinfo" component, as defined in
{{bibref|RFC3986}}.
HTTPS transport MUST be supported. Other optional transports MAY be
supported.
The absence of this parameter indicates that the Deployment Unit is unsigned. If
this is contrary to the security policy of the device then the command
will be rejected.
Install one or more Deployment Units (DUs) to the associated
{{object}}.
The {{datatype}} that specifies the location of the Deployment Unit to be
installed.
The URL MUST NOT include the "userinfo" component, as defined in
{{bibref|RFC3986}}.
The HTTPS transport MUST be supported, and the HTTP transport MAY
be supported. Other optional transports MAY also be supported.
The UUID (see {{bibref|RFC4122}}) of the Deployment Unit to be installed.
If this parameter is {{empty}} the device MUST generate the UUID
based on the rules defined in {{bibref|RFC4122}} and
{{bibref|TR-181i2|Annex C}}.
Username to be used by the device to authenticate with the file
server, if authentication is required.
Password to be used by the device to authenticate with the file
server, if authentication is required.
This parameter indicates whether the application runs in privileged mode.
{{false}} - Unprivileged Container.
{{true}} - Privileged Container.
Number of UIDs (Execution Unit User Identifiers) that this container will need as part of its
user namespace. UIDs are unique identifiers associated with each user and system
process that is used to determine the allocation and isolation of system resources.
{{deprecated|2.19|because this parameter should not be required.}}
A reference to the Execution Environment upon which the Deployment Unit is to
be installed.
If {{empty}} the device MUST choose the Execution Environment to
use.
The delay in {{units}} before which the container is shutdown.
This delay ensures that the application has enough time to perform any cleanup before
the Execution Unit transitions to idle state.
The default value is 10 seconds.
The roles which the application installed by this command will
need to be assigned in order to be able to function at all. If
any of these roles are not present in the
{{param|#.ExecEnv.{i}.AvailableRoles}} of the
{{object|#.ExecEnv}} into which the Deployment Unit is to be installed then
the command will fail. Some Agents may apply further filtering
for roles which are considered security- or privacy-sensitive.
Each entry in the list is the Name of a row in
{{object|##.LocalAgent.ControllerTrust.Role}}. If there is no
such row then the command will fail, as installation requires a
role which is not available on the Device.
If this argument is absent or empty then no roles are required in
order for the application to function.
The additional roles which the application installed by this
command would need to be assigned in order to be able to provide
its full functionality.
Each entry in the list is the Name of a row in
{{object|##.LocalAgent.ControllerTrust.Role}}. If there is no
such row, or the matching row is not present in the
{{param|#.ExecEnv.{i}.AvailableRoles}} of the Execution
Environment into which the Deployment Unit is to be installed, then the entry
will be ignored. Some Agents may apply further filtering for
roles which are considered security- or privacy-sensitive.
If this argument is absent or empty then no additional roles are
required in order for the application to be able to provide its
full functionality.
The User Roles which the application installed by this command will
need to be assigned in order to be able to function at all. If
any of these User Roles are not present in the
{{param|#.ExecEnv.{i}.AvailableUserRoles}} of the
{{object|#.ExecEnv}} into which the Deployment Unit is to be installed then
the command will fail. Some Agents may apply further filtering
for User Roles which are considered security- or privacy-sensitive.
Each entry in the list is the Name of a row in
{{object|##.Users.Role}}. If there is no
such row then the command will fail, as installation requires a
User Role which is not available on the Device.
The resulting capabilities list of the required User Roles
is listed in {{param|##.ExecutionUnit.{i}.AvailableUserRoleCapabilities}}.
If this argument is absent or empty then no User Roles are required in
order for the application to function.
Each entry in the list is an Object Path, Command Path, Event Path, or Parameter Path that determines the
element(s) of the data model that the application installed by this command has permission to register.
The information provided in this input arguement is placed in the {{object|##.USPServices.Trust}} table.
If this argument is absent or empty then the application has no permission to register any data model paths.
Defines the parameters of the auto-restart algorithm for any
{{object|##.ExecutionUnit}} which is created as a result of this
command.
An auto-restart may be triggered if the Agent determines that the
Execution Unit has terminated abnormally. An exponential backoff algorithm is
applied (increasing each time the delay before the Execution Unit is
re-launched) in order to prevent continual re-starting of the Execution Unit.
The retry interval range is controlled by two Parameters,
{{param|RetryMinimumWaitInterval}} and
{{param|RetryIntervalMultiplier}}.
Let ''m'' be the value of {{param|RetryMinimumWaitInterval}},
''k'' the value of {{param|RetryIntervalMultiplier}}, and ''n''
the current value of
{{param|##.ExecutionUnit.{i}.AutoRestart.RetryCount}}. Then on
the next occasion that the Agent determines that the Execution Unit has
terminated abnormally, the delay before re-starting the Execution Unit must
lie between ''m * (k/1000)^n^'' and ''m * (k/1000)^(n+1)^''
seconds, so long as ''m * (k/1000)^n^'' evaluates to a value less
than {{param|RetryMaximumWaitInterval}}. Once this point has been
reached, on all subsequent occasions that the Agent determines
that the Execution Unit has terminated abnormally the delay before
re-starting the Execution Unit must lie between
{{param|RetryMaximumWaitInterval}}'' * (1000/k)'' and
{{param|RetryMaximumWaitInterval}} seconds.
Enable the auto-restart feature for any
{{object|##.ExecutionUnit}} which is created as a result of
this command.
Configures the initial delay in {{units}} between detecting
that the Execution Unit has terminated abnormally and re-starting it.
Maximum delay in {{units}} between detecting that the Execution Unit has
terminated abnormally and re-starting it.
Configures the retry interval multiplier. This value is
expressed in units of 0.001, so for example a value of 2000
will result in the retry interval being doubled each time.
Configures the maximum number of consecutive restarts (as shown
in {{param|##.ExecutionUnit.{i}.AutoRestart.RetryCount}}) after
which no more attempts will be performed. A value of zero means
that the number of attempts is unlimited.
If the Execution Unit runs for this number of {{units}} without terminating
abnormally the Agent MAY reset its
{{param|##.ExecutionUnit.{i}.AutoRestart.RetryCount}} to zero,
thereby resetting the exponential backoff algorithm. A value of
zero disables this behavior.
Defines the resource restrictions for any Execution Unit which is
created by installation of the Deployment Unit. If this object is
absent then no resource restrictions will be applied.
The amount of disk space measured in {{units}} allocated to any
{{object|##.ExecutionUnit}} which is created as a result of
this command. If this parameter is omitted or has the value -1
then no disk space constraint will be applied.
The amount of physical RAM measured in {{units}} allocated to
any {{object|##.ExecutionUnit}} which is created as a result of
this command. If this parameter is omitted or has the value -1
then no memory constraint will be applied.
The CPU power measured in {{units}} allocated to any
{{object|##.ExecutionUnit}} which is created as a result of
this command, as a fraction (in {{units}}) of the CPU
allocation of the {{object|##.ExecEnv}} into which the
{{object|##.DeploymentUnit}} is installed. If this parameter is
omitted or has the value -1 then no CPU power constraint will
be applied.
The application data volumes which are required for correct
functioning of the {{object|##.DeploymentUnit}}. The device
should create these application data volumes and add them to the
{{object|##.ExecEnv.{i}.ApplicationData}} table, with the UUID of
the Deployment Unit as ApplicationUUID.
The application data will be lost when
{{template|DUStopped}}.
The application data will be retained after
{{template|DUStopped}}, and also across a device reboot
or a restart of the {{object|##.DeploymentUnit}}.
The application data will be lost on removal of the
{{object|##.ExecEnv}} in which the Deployment Unit is to
be installed.
The application data will be retained on {{command|##.DeploymentUnit.{i}.Update()}} or
{{command|##.DeploymentUnit.{i}.Uninstall()}} if and only if {{template|RetainDataTrue}}.
This parameter describes the {{object|##.ExecutionUnit.{i}.HostObject}} instances
which should be added to any {{object|##.ExecutionUnit}} created by
installation of the Deployment Unit.
This parameter describes the {{object|##.ExecutionUnit.{i}.EnvVariable}} instances
which should be added to any {{object|##.ExecutionUnit}} created by
installation of the Deployment Unit.
Version of the {{object}} as optionally set by the Controller.
Specifies the network configuration for any Execution Unit which is created by the installation of the DeploymentUnit.
When this argument or any of its child objects are missing,
the corresponding absent part is considered unnecessary and will not be available to the ExecutionUnit.
Specifies whether the resulting Execution Unit will share the
same network namespace as its ExecEnv parent or not.
If this parameter is set to {{true}},
both {{param|AccessInterfaces}} list and
{{object|NetworkConfig.PortMapping.{i}.}} input arguments will be ignored.
The default value MUST be {{false}}.
The network interfaces which the application installed by this command will be allowed to send traffic through it.
If any of these access interface are not present in the {{param|.SoftwareModules.ExecEnv.{i}.AvailableAccessInterfaces}}
of the ExecEnv into which the Deployment Unit is to be installed then the command will fail.
Some Agents may apply further filtering for access interfaces which are considered security- or privacy-sensitive.
Each entry in the list is the Name of a row within either {{object|.Logical.Interface.}} or {{object|.IP.Interface.}}.
If Name is present in both {{object|.Logical.Interface.}} and {{object|.IP.Interface.}}, the Interface referenced in
{{object|.Logical.Interface.}} must be selected.
If there is no such row then the command will fail, as installation requires access to a network, through the interface, which is not available.
When this argument is absent or {{empty}} then no outgoing network access is required for the Execution Unit to function.
Defines the list of required port mapping rules for any Execution Unit which
is created as a result of this command.
If this command encounters any issue in providing the requested mapping, such as the port already being used or reserved, then it will fail.
Name of a row within either {{object|.Logical.Interface.}} or {{object|.IP.Interface.}}. If Name is present in both {{object|.Logical.Interface.}}
and {{object|.IP.Interface.}}, the Interface referenced in {{object|.Logical.Interface.}} must be selected.
Specifies the interface to which the port mapping applies.
The external port that the NAT gateway would listen on for traffic to a
corresponding InternalPort. Inbound packets to this external port on the selected
interface MUST be forwarded to the IP address associated with the Execution Unit on the InternalPort.
The port on Execution Unit that the gateway MUST forward traffic to.
The protocol of the port mapping.
The Universally Unique Identifier that was either provided by the Controller, or
generated by the device, when this Deployment Unit was installed.
The format of this value is defined by {{bibref|RFC4122}} Version 5
(Name-Based) and {{bibref|TR-181i2|Annex C}}.
Version of the installed Deployment Unit. The format of this value is Execution
Environment specific.
A reference to the {{object|##.ExecEnv}} where the Deployment Unit was installed.
This event informs a Controller of the completion (successful or
unsuccessful) of a Deployment Unit state change.
When used, this event MUST be issued after the device has completed
any file transfers and carried out all operations related to the Deployment Unit
State Change.
This event MAY contain the results from multiple Deployment Unit state changes; it
is implementation specific how the device chooses to aggregate the Deployment Unit
state changes, although the device MUST notify the Controller of any
Deployment Unit state changes within 24 hours of the time the operations were
completed by the device.
The device SHOULD make every attempt to aggregate, as much as
possible, the Deployment Unit State Change notifications to the Controller in the
interest of scalability.
The UUID as defined in {{bibref|RFC4122}} of the Deployment Unit that affected
by the state change.
A reference to the Deployment Unit that was affected by the state change.
In the case of an Install, this will be the version of the Deployment Unit
created. In the case of an Update, it will be the updated version
of the Deployment Unit. In the case of an Uninstall, it will be the version of
the uninstalled Deployment Unit.
This MUST match the {{param|#.DeploymentUnit.{i}.Version}}
Parameter contained within the instance of the Deployment Unit that
is contained within the {{param|DeploymentUnitRef}} argument.
The current state of the created Deployment Unit.
The Deployment Unit is in an Installed state due to one of the following:
successful Install, successful Update, failed Update, or
failed Uninstall. In the case of a failed Update or failed
Uninstall the Fault argument will contain an explanation of
the failure.
The Deployment Unit was successfully uninstalled from the device.
{{deprecated|2.19|due to a typographical error in capitalization}}
The Deployment Unit was successfully uninstalled from the device.
The Deployment Unit could not be installed in which case a Deployment Unit instance
MUST NOT be created in the Data Model.
Whether or not the Deployment Unit operation resolved all of its dependencies.
In the case of a successful Uninstall, this value is meaningless
and should be {{true}}.
The Execution Units affected by this operation.
In the case of an Install, this will be the list of Execution Units that were
created as a result of the Deployment Unit’s installation.
In the case of an Update, this will be the list of all Execution Units
currently associated with the updated Deployment Unit, including those that were
created through the initial Deployment Unit installation and any updates that
had already occurred but not including any Execution Units that no longer exist
on the device because of this or previous updates.
In the case of an Uninstall, this will be the list of the Execution Units
removed from the device due to the Deployment Unit being removed.
The date and time transfer was started in UTC. The device SHOULD
record this information and report it in this argument, but if this
information is not available, the value of this argument MUST be
set to the Unknown Time value.
The date and time the transfer was fully completed and applied in
UTC. This need only be filled in if the transfer has been fully
completed and applied. The device SHOULD record this information
and report it in this argument, but if this information is not
available or the transfer has not completed, the value of this
argument MUST be set to the Unknown Time value.
The operation that was performed against the Deployment Unit causing the Deployment Unit
state change.
The operation attempted was the Installation of a Deployment Unit.
The operation attempted was the Update of an existing Deployment Unit.
The operation attempted was the Un-Installation of an
existing Deployment Unit.
Fault Structure. If the operation was successful, the
{{param|FaultCode}} MUST be zero. Otherwise a non-zero
{{param|FaultCode}} is specified along with a {{param|FaultString}}
indicating the failure reason.
The numerical fault code. Valid values are:
*If the operation was successful, the fault code is 0.
*If the device cannot complete the operation for some unknown
reason, it SHOULD reject the operation with a 7002 (Request
Denied) fault code.
*If the device detects the presence of the "userinfo" component
in the file source URL, it SHOULD reject the operation with a
7004 (Invalid Arguments) fault code.
*If the device cannot find the Execution Environment specified in
the Install or Update command, it SHOULD reject the operation
with a 7223 (Unknown Execution Environment) fault code.
*If the device determines that the Deployment Unit being
installed does not match either the Execution Environment
specified or any Execution Environment on the device, it SHOULD
reject the operation with a 7225 (Deployment Unit to Execution
Environment Mismatch) fault code
*If the device detects that the Deployment Unit being installed
already has the same version as one already installed on the
same Execution Environment, it SHOULD reject the operation with
a 7226 (Duplicate Deployment Unit) fault code.
*If the device detects that that there are no more system
resources (disk space, memory, etc.) to perform the Install or
Update of a Deployment Unit, it SHOULD reject the operation with
a 7227 (System Resources Exceeded) fault code.
*If a requested operation attempts to alter the State of a
Deployment Unit in a manner that conflicts with the Deployment
Unit State Machine Diagram {{bibref|TR-369|Appendix I "Software
Module Management"}}, it SHOULD reject the operation with a 7229
(Invalid Deployment Unit State) fault code.
*If a requested operation attempts to Uninstall a Deployment Unit that caused
an EE to come into existence, where that EE has at least 1
installed Deployment Unit or at least 1 child EE, then the device SHOULD
reject the operation with a 7229 (Invalid Deployment Unit State)
fault code.
*If a requested operation attempts to Uninstall a Deployment Unit that caused
an ExecEnvClass to come into existence, where at least one EE
exists which instantiates that ExecEnvClass, then the device
SHOULD reject the operation with a 7229 (Invalid Deployment Unit
State) fault code.
*If a requested operation attempts to Install or Update a Deployment Unit and
the server specified in the URL is not currently reachable or
the request times out, then the device SHOULD reject the
operation with a 7033 (Server Unreachable) fault code.
*If a requested operation attempts to Install or Update a Deployment Unit and
the server specified in the URL fails security checks (e.g. by
not presenting a valid certificate), then the device SHOULD
reject the operation with a 7034 (Server Insecure) fault code.
*If a requested operation attempts to Install or Update a Deployment Unit and
the file returned by the server appears to be corrupt, then the
device SHOULD reject the operation with a 7035 (Corrupt Data)
fault code.
*If a requested operation attempts to Install or Update a Deployment Unit and
the file returned by the server does not match the signature
provided, or a required signature is absent, then the device
SHOULD reject the operation with a 7036 (Bad Signature) fault
code.
*If a requested operation attempts to Install or Update a Deployment Unit
and includes a RequestedRole argument which contains at least
one Role which is not in the EE's AvailableRoles list, then the
device SHOULD reject the operation with a 7032 (Unavailable
Role) fault code.
*If a requested operation attempts to Install or Update a Deployment Unit
and includes a RequestedUserRole argument which contains at least
one User Role which is not in the EE's AvailableUserRoles list, then the
device SHOULD reject the operation with a 7037 (Unavailable
User Role) fault code.
A human-readable text description of the fault. This field SHOULD
be empty if the FaultCode equals 0 (zero).
Create a new Execution Environment of this class.
An optional input the Controller can use to specify the
{{param|###.ExecEnv.{i}.Alias}} value for the new instance. If
provided as an input and the value already exists in
{{object|###.ExecEnv.{i}}}, this command will fail.
Suggested value for the {{param|###.ExecEnv.{i}.Name}} of the new
instance. If provided as an input and the value already exists in
{{object|###.ExecEnv.{i}}}, this command will fail.
The ExecEnv instance of which the new instance should be a child.
The roles which are available to Deployment Units installed into
the new instance. Only the listed roles may be assigned to any
Deployment Unit installed into the instance. If this parameter is
missing or {{empty}} then no roles may be assigned to any
Deployment Unit installed into the instance.
Each entry in the list is the Name of a row in
{{object|###.LocalAgent.ControllerTrust.Role}}. If there is no
such row then the entry will be ignored.
The User Roles which are available to Deployment Units installed into
the new instance. Only the listed User Roles may be assigned to any
Deployment Unit installed into the instance. If this parameter is
missing or {{empty}} then no User Roles may be assigned to any
Deployment Unit installed into the instance.
Each entry in the list is the Name of a row in
{{object|###.Users.Role}}. If there is no
such row then the entry will be ignored.
If this parameter is present and is {{true}}, the created ExecEnv
will have its {{param|##.ExecEnv.{i}.Enable}} flag set {{true}}
and it will immediately transition to Status
{{enum|Up|##.ExecEnv.{i}.Status}}. Otherwise the ExecEnv will
initially be Disabled, allowing the Controller to set further
parameters before enabling the ExecEnv.
A reference to the {{object|##.ExecEnv}} which was created.
If an Update or Uninstall operation is attempted on a
{{object|#.DeploymentUnit}} that is to be applied against a disabled
{{object}}, that operation fails and the associated event will
contain a FaultStruct for that operation.
Disabling an Execution Environment could place the device in a
non-manageable state. For example, if the operating system itself was
modeled as an {{object}} and a Controller disabled it, the Agent
might be terminated leaving the device unmanageable.
The run level that this {{object}} is currently operating in. This
value is altered by executing the {{command|SetRunLevel()}} command.
Upon startup (whether that is caused by a device Boot or the
Execution Environment starting) {{param}} will be equal to
{{param|InitialRunLevel}}, unless Run Levels are not supported by
this {{object}} in which case {{param}} will be -1.
Run levels dictate which Execution Units will be started. Execution
Units will be started if {{param}} is greater than or equal to
{{param|#.ExecutionUnit.{i}.RunLevel}} and
{{param|#.ExecutionUnit.{i}.AutoStart}} is {{true}}.
If {{param}} is -1 then Run Levels are not supported by this
{{object}} and setting {{param|InitialRunLevel}} or executing the
command {{command|SetRunLevel()}} will not impact the Run Level of
this {{object}}.
This value can be altered by executing the
{{command|ModifyConstraints()}} command.
This value can be altered by executing the
{{command|ModifyConstraints()}} command.
This value can be altered by executing the
{{command|ModifyConstraints()}} command.
This parameter is set each time the {{object}} is restarted. It is
cleared each time that parameter {{param|Enable}} is set {{false}}
for any reason other than a restart of the {{object}}.
If the restart was the result of invoking the {{command|Restart()}}
command then the value will be taken from the Reason parameter of the
command.
The number of times the {{object}} has been restarted since it was
last disabled.
The time at which the {{object}} was last restarted. Initially this
parameter is set to the Unknown Time (0001-01-01T00:00:00Z).
If the device stores the acceptable public keys for signing in X.509
certificates, this parameter identifies which certificates contain
public keys which can be used to verify the signature of a
DeploymentUnit.
Not all devices will use X.509 certificates to store the public keys.
In devices which do not use X.509 certificates for this purpose, this
parameter will be empty.
The roles which are available to Deployment Units installed into this
{{object}}. Only the listed roles may be assigned to any
DeploymentUnit.
If this parameter is missing or {{empty}} then no roles will be
assigned to any Deployment Unit installed into this {{object}}.
Represents the network interface through which the outgoing traffic from the Execution Unit running in
this {{object}} may be allowed.
This value can be altered by executing the {{command|ModifyAvailableAccessInterfaces()}}.
The User Roles which are available to Deployment Units installed into this
{{object}}. Only the listed User Roles may be assigned to a
DeploymentUnit.
If this parameter is missing or {{empty}} then no User Roles will be
available to Deployment Units installed into this {{object}}.
Provides a mechanism to remotely manipulate the run level of this
{{object}}, meaning that altering this command will change the value
of the {{param|#.CurrentRunLevel}}.
Run levels dictate which Execution Units will be started. Execution
Units will be started if {{param|CurrentRunLevel}} is greater than or
equal to {{param|#.ExecutionUnit.{i}.RunLevel}} and
{{param|#.ExecutionUnit.{i}.AutoStart}} is {{true}}.
This parameter will request to change the value of the
{{param|#.CurrentRunLevel}} to the value of this parameter.
Setting this value when {{param|#.CurrentRunLevel}} is -1 has no
impact to the Run Level of this instance of the {{object|##.}}
object.
Provides a mechanism to remotely manipulate the resource constraints
applied to this {{object}}, thereby changing the value of
{{param|#.AllocatedDiskSpace}}, {{param|#.AllocatedMemory}}, or
{{param|#.AllocatedCPUPercent}}. A resource constraint will only be
modified if the corresponding parameter is present in the call to
{{command}}; all other resource constraints will be left unchanged,
Determines the behavior if a request is made which would reduce
the allocation of a resource below the amount which is currently
being used.
If {{param}} is {{false}} and any of the other parameters specify
a value which is less than the amount of the resource which is
currently being consumed, the Agent SHOULD reject the request
with error code 7022 and leave all resource allocations
unchanged.
if {{param}} is {{true}} and any of the other parameters specify
a value which is less than the amount of the resource which is
currently being consumed, the Agent MAY take steps to reduce the
resource consumption accordingly. These steps might include
forcing a restart of individual ExecutionUnits or of the whole
{{object}}. Use of Force = true may therefore lead to
unpredictable behaviour.
Modify the roles which are available to Deployment Units installed
into this {{object}}.
The command will fail if the new list of roles doesn't contain a required role of DeploymentUnit
installed previously into the {{object}}.
The new list of roles which may be assigned to any DeploymentUnit
installed into the {{object}}; this list replaces the previous
value of {{param|#.AvailableRoles}}. If this parameter is
{{empty}} then no roles may be assigned to any DeploymentUnit
installed into the {{object}}.
Each entry in the list is the Name of a row in
{{object|###.LocalAgent.ControllerTrust.Role}}.
The new list of User Roles which may be assigned to a DeploymentUnit
installed into the {{object}}; this list replaces the previous
value of {{param|#.AvailableUserRoles}}. If this parameter is
{{empty}} then no User Roles can be assigned to a DeploymentUnit
installed into the {{object}}.
Each entry in the list is the Name of a row in
{{object|###.Users.Role}}.
Modify the outgoing network traffic interfaces which are available to Deployment Units installed
into this {{object}}.
The command will fail if the new list of access interfaces doesn't contain an access interface required
for a Deployment Unit installed previously into the {{object}}.
The new list of access interfaces which may be assigned to any Deployment Unit installed into
the {{object}} this list replaces the previous value of {{param|#.AvailableAccessInterfaces}}.
If this parameter is an empty string then no access interface may be assigned to any DeploymentUnit
installed into the {{object}}.
Each entry in the list is the Name of a row in {{object|.Logical.Interface}}.
Restart this ExecEnv.
If the {{object}} is currently disabled, this command will fail and
the state of the {{object}} will not change.
If the {{object}} is currently enabled, this command has the
following effect:
# The {{object}} transitions to status {{enum|Restarting|Status}}.
# All Deployment Units installed to the {{object}} will be
unaffected, but any Execution Units currently running on the
{{object}} will automatically transition to
{{enum|Idle|#.ExecutionUnit.{i}.Status}}, exactly as if the
{{object}} had transitioned to status {{enum|Disabled|Status}}.
# As soon as all the Execution Units have transitioned to
{{enum|Idle|#.ExecutionUnit.{i}.Status}}, the {{object}}
transitions to status {{enum|Up|Status}}. The Execution Units which
were running on the {{object}} will be restarted according to their
{{param|#.ExecutionUnit.{i}.AutoStart}} flag and
{{param|#.ExecutionUnit.{i}.RunLevel}}.
Textual description of the reason why this ExecEnv is being
restarted. This will be copied into the
{{param|##.RestartReason}} of the {{object|#}}.
If this parameter is set to true, the implementation MAY take
extra steps to ensure that all Execution Units transition to
{{enum|Idle|##.ExecutionUnit.{i}.Status}} within finite time.
This command causes this {{object}} to revert back to the state it
was in when the device last issued a Boot event with a cause of a
local or remote factory reset.
The following requirements dictate what MUST happen for the reset to
be complete:
# All Deployment Units that were installed after the last Boot (with
cause of a factory reset) event MUST be removed
# All persistent storage, configuration files, and log files that
were associated with the removed Deployment Units MUST be removed
# Any Deployment Unit that is still installed against the Execution
Environment MUST be restored to the version present when the last
Boot (with cause of a factory reset) event was issued
# Any Deployment Unit that was present when the last Boot (with cause
of a factory reset) event was issued, but was subsequently
uninstalled and is now not present, MUST be installed with the
version that was present when the last Boot (with cause of a
factory reset) event was issued
# The Execution Environment MUST be restored to the version and
configuration present when the last Boot (with cause of a factory
reset) event was issued
# The Execution Environment MUST be restarted after all other
restoration requirements have been met
This command removes the {{object}} from the device. The command will
always fail if the {{object}} has at least 1 child {{object}}; the
behaviour in the case that the {{object}} has at least 1 installed
{{object|#.DeploymentUnit}} depends on the value of the Force
parameter.
If this parameter is present and is {{true}}, the ExecEnv will be
removed even if one or more Deployment Unit is installed in it. A
{{event|###.DUStateChange!}} Event with
{{param|###.DUStateChange!.OperationPerformed}} set to
{{enum|Uninstall|###.DUStateChange!.OperationPerformed}} will be
issued for each Deployment Unit which is removed as a result of the operation.
Any Application Data associated with the Deployment Unit will be lost.
If this parameter is absent or {{false}}, the operation will fail
if any Deployment Unit is installed in the EE; in the case of such a failure
the EE will continue to exist and its Status will not change, nor
will any Application Data be lost.
This event informs a Controller when an {{object}} has been
restarted.
The time at which the restart was initiated.
If the restart was initiated by a an invocation of the
{{command|#.Restart()}} command then this parameter is copied from
the Reason parameter of that command.
The entries in this table are created automatically as a result of
calls to {{command|##.InstallDU()}} and
{{command|##.DeploymentUnit.{i}.Update()}}, and are removed as a result
of calls to {{command|##.DeploymentUnit.{i}.Update()}},
{{command|##.DeploymentUnit.{i}.Uninstall()}}, and
{{command|Remove()}}.
Note that if this parameter has the value {{enum|Forever}}, it is
possible that there is no currently installed
{{object|##.DeploymentUnit}} whose
{{param|##.DeploymentUnit.{i}.UUID}} matches the
{{param|ApplicationUUID}} of this {{object|#}} table entry; this
situation will be resolved when either a matching
{{object|##.DeploymentUnit}} is re-installed, or this volume is
removed using the {{command|Remove()}} command.
The application data will be lost when {{template|DUStopped}}.
The application data will be retained after
{{template|DUStopped}}, and also across a device reboot or a
restart of the {{object|###}}.
The application data will be lost if the {{object|###}} is
removed.
The application data will be retained on {{command|##.DeploymentUnit.{i}.Update()}} or
{{command|##.DeploymentUnit.{i}.Uninstall()}} if and only if {{template|RetainDataTrue}}.
Remove this row from the table, together with the associated
application data volume.
Version of the {{object}} as optionally set by the Controller during {{command|#.InstallDU()}} command or {{command|Update()}}.
Contains the {{datatype}} used by the most recent
{{command|#.InstallDU()}} or {{command|Update()}} to either Install
or Update this {{object}}.
The internal Controller which the application installed by this
{{object}} uses to access the Data Model. Will be {{empty}} if the
application does not require Data Model access.
Update the associated {{object}}.
The {{datatype}} that specifies the location of the Deployment Unit to be
installed.
The URL MUST NOT include the "userinfo" component, as defined in
{{bibref|RFC3986}}.
The HTTPS transport MUST be supported, and the HTTP transport MAY
be supported. Other optional transports MAY also be supported.
If the device receives an Update command with the same source URL
as a previous Update or Install command, the device MUST perform
each Update as requested, and MUST NOT assume that the content of
the file to be downloaded is the same each time.
Username to be used by the device to authenticate with the file
server, if authentication is required.
Password to be used by the device to authenticate with the file
server, if authentication is required.
This parameter determines whether the application runs in privileged mode.
{{false}} - Unprivileged Container.
{{true}} - Privileged Container.
Number of UIDs (Execution Unit User Identifiers) that this container will need as part of its
user namespace. UIDs are unique identifiers associated with each user and system
process that is used to determine the allocation and isolation of system resources.
{{deprecated|2.19|because this parameter should not be required.}}
If this argument is present, it lists the roles which the
application will need to be assigned in order to be able to
function at all after this update. If it is absent then the
required roles are unchanged from the previous version.
If any of these roles are not present in the
{{param|##.ExecEnv.{i}.AvailableRoles}} of the
{{object|###.ExecEnv}} in which the Deployment Unit is installed then the
command will fail. Some Agents may apply further filtering for
roles which are considered security- or privacy-sensitive.
Each entry in the list is the Name of a row in
{{object|###.LocalAgent.ControllerTrust.Role}}. If there is no
such row then the command will fail, as installation requires a
role which is not available on the Device.
If this argument is empty then no roles are required in
order for the application to function.
If this argument is present, it lists the additional roles which
the application would need to be assigned in order to be able to
provide its full functionality after this update. If it is absent
then the required roles are unchanged from the previous version.
Each entry in the list is the Name of a row in
{{object|###.LocalAgent.ControllerTrust.Role}}. If there is no
such row, or the matching row is not present in the
{{param|##.ExecEnv.{i}.AvailableRoles}} of the Execution
Environment into which the Deployment Unit is to be installed, then the entry
will be ignored. Some Agents may apply further filtering, for
roles which are considered security- or privacy-sensitive.
If this argument is empty then no additional roles are
required in order for the application to be able to provide its
full functionality.
If this argument is present, it lists the User Roles which the
application will need to be assigned in order to be able to
function at all after this update. If it is absent then the
required User Roles are unchanged from the previous version.
If any of these User Roles are not present in the
{{param|##.ExecEnv.{i}.AvailableUserRoles}} of the
{{object|###.ExecEnv}} in which the Deployment Unit is installed then the
command will fail. Some Agents may apply further filtering for
User Roles which are considered security- or privacy-sensitive.
Each entry in the list is the Name of a row in
{{object|###.Users.Role}}. If there is no
such row then the command will fail, as installation requires a
User Role which is not available on the Device.
The resulting capabilities list of the required User Roles
is listed in {{param|##.ExecutionUnit.{i}.AvailableUserRoleCapabilities}}.
If this argument is {{empty}} then no User Roles are required in
order for the application to function.
Each entry in the list is an Object Path, Command Path, Event Path, or Parameter Path that determines the
element(s) of the data model that the application updated by this command has permission to register.
The information provided in this input argument is placed in the {{object|###.USPServices.Trust}} table,
replacing any existing paths that are associated with this application.
If this argument is absent then the registration permissions are unchanged from the previous version.
If this argument is {{empty}} then the application has no permission to register any data model paths.
Can be used to modify the resource restrictions for any Execution
Unit which is created by the DeploymentUnit. If this object is
absent then the resource restrictions will remain as they were
before the command was invoked.
The amount of disk space measured in {{units}} allocated to any
{{object|###.ExecutionUnit}} created by this command. A value
of -1 indicates that no disk space constraint is applicable.
If this parameter is not present then the allocated disk space
will remain unchanged.
The amount of physical RAM measured in {{units}} allocated to
any {{object|###.ExecutionUnit}} created by this command. A
value of -1 indicates that no memory constraint is applicable.
If this parameter is not present then the allocated memory will
remain unchanged.
The CPU power measured in {{units}} allocated to any
{{object|###.ExecutionUnit}} created by this command, as a
fraction (in {{units}}) of the CPU allocation of the
{{object|###.ExecEnv}} in which this {{object}} resides. A
value of -1 indicates that no CPU power constraint is
applicable.
If this parameter is not present then the allocated memory will
remain unchanged.
The application data volumes which are required for correct
functioning of the updated {{object|##}}.
The {{object|##}} may already have one or more existing
application data volumes, represented by entries in the
{{object|###.ExecEnv.{i}.ApplicationData}} table, which have
{{param|###.ExecEnv.{i}.ApplicationData.{i}.Retain}} equal to
{{enum|Forever|###.ExecEnv.{i}.ApplicationData.{i}.Retain}} and
{{param|###.ExecEnv.{i}.ApplicationData.{i}.ApplicationUUID}}
equal to the {{param|##.UUID}} of the {{object|##}} which is
being updated.
The behaviour with respect to these existing application volumes
depends on the value of the {{param|#.RetainData}} input
argument.
# If the {{param|#.RetainData}} input argument is {{false}} then
the device SHOULD remove these existing application data
volumes, and SHOULD treat the rows in this argument in the same
way as for the {{command|###.InstallDU()}} command.
# If {{param|#.RetainData}} is {{true}}, the device SHOULD
attempt to transfer the existing application data volumes to
the updated {{object|##}}.
## If an existing application data volume does not match the
{{param|Name}} of any row of this argument, then the device
SHOULD leave both the volume and its entry in the
{{object|###.ExecEnv.{i}.ApplicationData}} table unchanged.
## If the {{param|Name}} of a row of this argument does not match
the {{param|###.ExecEnv.{i}.ApplicationData.{i}.Name}} of any
existing application data volume, then the device SHOULD
attempt to create the volume together with its entry in the
{{object|###.ExecEnv.{i}.ApplicationData}} table.
## If the {{param|Name}} of a row of this argument matches the
{{param|###.ExecEnv.{i}.ApplicationData.{i}.Name}} of an
existing application data volume, then the device SHOULD
attempt to carry the application data forward to the updated
{{object|##}}. This may imply copying of the data if the
{{param|Capacity}}, {{param|Encrypted}}, or {{param|Retain}}
values in this argument differ from those in the
{{object|###.ExecEnv.{i}.ApplicationData}} table.
An attempt to create a new application data volume or to copy an
existing application data volume to a new location may cause the
operation to fail with a 7227 (System Resources Exceeded) fault
code.
Data will be lost when {{template|DUStopped}}.
The application data will be retained after
{{template|DUStopped}}, and also across a device reboot
or a restart of the {{object|###.ExecEnv}}.
The application data will be lost on removal of the
{{object|###.ExecEnv}} in which the {{object|##}} is
installed.
The application data will be retained on
{{command|###.Update()}} or {{command|###.Uninstall()}}
if and only if {{template|RetainDataTrue}}.
This parameter describes the
{{object|###.ExecutionUnit.{i}.HostObject}} instances which
should be present after the update in any
{{object|###.ExecutionUnit}} created by this DeploymentUnit. This
table supersedes any {{object|###.ExecutionUnit.{i}.HostObject}}
instances which may have been present before the update.
This parameter describes the
{{object|###.ExecutionUnit.{i}.EnvVariable}} instances which
should be present after the update in any
{{object|###.ExecutionUnit}} created by this DeploymentUnit. This
table supersedes any {{object|###.ExecutionUnit.{i}.EnvVariable}}
instances which may have been present before the update.
Version of the {{object}} as optionally set by the Controller.
When the argument is absent then {{param}} is unchanged.
Specifies the network configuration for any Execution Unit which is created by the update of the DeploymentUnit. The new network configuration supersedes any previous configuration.
When this argument is not present in the {{command|.SoftwareModules.DeploymentUnit.{i}.Update()}},
the network configuration remains unaltered.
Specifies whether the resulting Execution Unit will share the
same network namespace as its ExecEnv parent or not.
If this parameter is set to {{true}},
both {{param|AccessInterfaces}} list and
{{object|NetworkConfig.PortMapping.{i}.}} input arguments will be ignored.
The default value MUST be {{false}}.
The network interfaces which the application updated by this command will be allowed to send traffic through it.
If any of these access interface are not present in the {{param|.SoftwareModules.ExecEnv.{i}.AvailableAccessInterfaces}}
of the ExecEnv into which the Deployment Unit is to be updated then the command will fail.
Some Agents may apply further filtering for access interfaces which are considered security- or privacy-sensitive.
Each entry in the list is the Name of a row within either {{object|.Logical.Interface.}} or {{object|.IP.Interface.}}.
If Name is present in both {{object|.Logical.Interface.}} and {{object|.IP.Interface.}}, the Interface referenced in
{{object|.Logical.Interface.}} must be selected.
If there is no such row then the command will fail, as the update requires access to a network, through the interface, which is not available.
When the argument {{object|NetworkConfig}} is absent or {{empty}} for the {{command|.SoftwareModules.DeploymentUnit.{i}.Update()}},
the {{param}} network configuration remains unaltered.
When the argument {{object|NetworkConfig}} provided in {{command|.SoftwareModules.DeploymentUnit.{i}.Update()}}, {{param}} configuration supersedes
any previous configuration. If {{param}} is absent or {{empty}}, it indicate that no outgoing network access is required for the resulting
Execution Unit to function.
Defines the list of required port mapping rules for any Execution Unit which
is created as a result of this command.
If this command encounters any issue in providing the requested mapping, such as the port already being used or reserved, then it will fail.
When the argument {{object|NetworkConfig}} is absent or {{empty}} for the {{command|.SoftwareModules.DeploymentUnit.{i}.Update()}},
the {{object}} network configuration remains unaltered.
When the argument {{object|NetworkConfig}} provided in {{command|.SoftwareModules.DeploymentUnit.{i}.Update()}}, {{object}} configuration supersedes
any previous configuration. If {{object}} is absent or {{empty}}, it indicate that no port mapping is required for the resulting Execution Unit to function.
Name of a row within either {{object|.Logical.Interface.}} or {{object|.IP.Interface.}}. If Name is present in both {{object|.Logical.Interface.}}
and {{object|.IP.Interface.}}, the Interface referenced in {{object|.Logical.Interface.}} must be selected.
Specifies the interface to which the port mapping applies.
The external port that the NAT gateway would listen on for traffic to a
corresponding InternalPort. Inbound packets to this external port on the selected
interface MUST be forwarded to the IP address associated with the Execution Unit on the InternalPort.
The port on Execution Unit that the gateway MUST forward traffic to.
The protocol of the port mapping.
Uninstall the associated {{object}}.
This instance is in the process of Restarting and SHOULD
transition to the {{enum|Active}} state.
NOTE: All other objects and parameters (i.e. not multi-instanced
objects) that this {{object}} has caused to come into existence can
be discovered via the GetSupportedDM and GetInstances USP messages.
Each item in the list represents a mandatory ControllerTrust Role that was required by
{{param|#.InstallDU().RequiredRoles}} or
{{param|#.DeploymentUnit.{i}.Update().RequiredRoles}} when the {{object}}
was created or updated.
Note, the description of the {{object|.LocalAgent.ControllerTrust.Role.}} table indicates
that the device MAY reject deletion requests for specific instances of that object, which
could cause instability for this {{object}}.
Each item in the list represents an optional ControllerTrust Role that was required by
{{param|#.InstallDU().OptionalRoles}} or
{{param|#.DeploymentUnit.{i}.Update().OptionalRoles}} when the {{object}}
was created or updated.
Each item in the list represents a User Role that was required by
{{param|#.InstallDU().RequiredUserRoles}} or
{{param|#.DeploymentUnit.{i}.Update().RequiredUserRoles}} when the {{object}}
was created or updated.
Note, the description of the {{object|.Users.Role.}} table indicates
that the device MAY reject deletion requests for specific instances of that object, which
could cause instability for this {{object}}.
This is the list of User Role instances that in turn yields a set of capabilities available to this {{object}}.
This list is evaluated only at the start of this {{object}} based on the
configuration of {{param|RequiredUserRoles}} and
{{param|.Users.Role.{i}.RequiredCapabilities}}.
Set the state transition that the Controller is requesting for this
instance of the {{object}} object.
If this instance of the {{object}} object is associated with an
Execution Environment that is disabled and an attempt is made to
alter this value, then a error message MUST be generated.
Indicates the requested state to transition this instance of the
{{object|##.}} object. {{enum}}
If this {{object|##.}} is currently in
{{enum|Starting|###.ExecutionUnit.{i}.Status}} or
{{enum|Active|###.ExecutionUnit.{i}.Status}} the device
will attempt to Stop the Execution Unit; otherwise this
requested state is ignored.
If this {{object|##.}} is currently in
{{enum|Idle|###.ExecutionUnit.{i}.Status}} the device will
attempt to Start the Execution Unit.
If this {{object|##.}} is in
{{enum|Stopping|###.ExecutionUnit.{i}.Status}} the request
is rejected and a fault raised. Otherwise this requested
state is ignored.
Initiate a restart of the ExecutionUnit.
If this {{object}} is currently in status
{{enum|Idle|##.ExecutionUnit.{i}.Status}} the device will attempt to
start the Execution Unit, as if {{command|#.SetRequestedState()}} had
been called with {{param|#.SetRequestedState().RequestedState}} set
to {{enum|Active|#.SetRequestedState().RequestedState}}.
If this {{object}} is in status
{{enum|Stopping|##.ExecutionUnit.{i}.Status}} the request is rejected
and a fault raised.
If this {{object}} is currently in status
{{enum|Starting|##.ExecutionUnit.{i}.Status}} or
{{enum|Active|##.ExecutionUnit.{i}.Status}} the device will attempt
to stop the Execution Unit and will place it in the
{{enum|Restarting|##.ExecutionUnit.{i}.Status}} state. Once the
{{object|##.}} has stopped the device will attempt to re-start the
Execution Unit.
If this {{object|##.}} is in any other status then this command has
no effect.
Invoking the {{command|#.Restart()}} command
also has the effect of resetting this parameter to zero.
It is also possible for the Execution Unit to expose status and
configuration parameters within Service objects or as embedded objects
and parameters directly within the root data model, in which case the
combination of {{param|#.References}} and use of GetSupportDM and
GetInstances USP messages will be used to determine their locations.