Introduction

The instructions in this article describe the creation of a package that can be deployed to registered devices (individually or as a group). The steps apply to all different types of deployable material, including OS images, applications, and other files such as media content or configuration files.

Please be aware that updating devices with new OS images requires the use of a hidden SquareOne Recovery partition. This needs to be created in advance. More information can be found in SquareOne Imaging.

Topic Links

Create a Package/Version

Editing a Draft Version

Publishing a Version

Creating a new Version

Retiring a Version

Package Installations Requiring a Reboot

Package Examples

Create a Package/Version

To create a new package for deployment to one device or a group of devices, click the + icon in the Packages Screen to begin creating a new package. Work through the sections completing the information requested as described in the following steps.

Note that a newly created version is created in a Draft state. This allows the version to be edited and  tested before publishing (see sections Editing a Draft Version and Publishing a Version). 

In the Create Package dialog, provide a name, category and (optional) description.

Note that the category (OS, Application, Lambda and Other) does not have a functional effect but can be useful for organizing and filtering. 

Once completed, the Edit Draft screen will be displayed:

In the Create Version section:

• Provide a name for the Version. This can be a free-form string, but a semantic version (e.g. X.Y.Z) is recommended where possible.
• Optionally provide a longer Description and Release Notes
• Set the Installation timeout - this should be set accordingly to detect a failed installation. Note that it is recommended to set this to at least 1 hour as the timeout is not checked at a high frequency. 

Now configure one (or more) Install Configurations. By default, a configuration for all OS/Architecture types is created (note the target is titled all/all), but this can be configured to be more specific. By creating multiple Targets within a version, it is possible to create (for example) a version of a package that can be deployed to Windows and Linux devices of varying architectures.

Complete the fields as appropriate:

• The Architecture and OS define the compatibility of this Target. 
• A single File must be uploaded to form the target file for this Target of the the package version.
• The Install Type defines how the package is handled by the device:
  1. Copy: The file will be copied to the destination path specified.
  2. Debian Package: The file will be installed by a Debian package manager on the device (Applicable for Linux only).
  3. Gzipped Tarball: The file will be untarred and unzipped to the destination path specified.
  4. Run as Installer: The file will be executed on download to install the package. Note: installers deployed in this manner should complete silently, requiring no input from the user. If a package requires a command line parameter to install silently, then use the Copy type and specify the full command to install the package as the post-install command
  5. Zip: The file will be unzipped to the destination path specified.
  6. OS: The file will be treated as an Operating System image/installer. Suitable post-install commands will be seeded if the Target OS is set to Linux or Windows. See the OS imaging articles for more detail (SquareOne Imaging).
  7. Android App Bundle (AAB): The file will be installed as an Android App Bundle
  8. Android Package (APK): The file will be installed as an Android Package
  9. Lua Lambda: This install type is used to deploy custom code, and is not currently supported for external use. 
• The File Name is the name the file will have on the target devices. 
  • Note: Ensure that the chosen filename will be valid on the operating systems of all the expected target devices. For example, Windows prohibits specific characters in filenames. 
• The Destination Path (if shown) defines where the file will be deployed to on the target devices

Additional options are shown by toggling the Show Advanced control:

Post Install Commands

• The Post-install command is a command that the device will run on completion of install. 
  • The Post-Install command can be used for clean-up, required post-install configuration updates or execution, or to run an installer package in silent mode. For example, if the package is a media file, a post-install step could be used to call or restart an appropriate application to pick up the newly installed content.
  • Some examples can be found in Package Examples and Command Examples. Note the command must contain the fully qualified filename including directory and extension.

Package Control

• The Start and Stop commands are commands that are exposed in the UI to allow a user to easily start and stop the package. For example:
• The Processes to Monitor option allows a list of one or more processes to be provided that will be monitored by the SquareOne agent to track if/when the software is running or not. Note that this list is case-sensitive.

Editing a Draft Version

It is possible to edit a Draft Version by clicking the pencil icon in a list where the version is shown. For example, in the Edit Drafts screen:

Makes changes to the fields as described in the Create a Package/Version section, above. 

When the changes are saved, the Draft number is updated (and the previous Draft version is Retired). 

Drafts may be deployed as normal, and when they have been proven, they can be formally published, as described below. 

Publishing a Version

When a package draft version has been tested and proven, it can be Published by clicking the  icon to Change Approval State:

From here, the following dialog is displayed:

Choosing Publish retires the last Draft Version and created a Published Version with the Draft suffix is removed. 

Creating a new Version

Additional versions of a software package can be created using the large + icon to create a new version from scratch, or by using the  icon to create a new version from an existing version.

Retiring a Version

When a package is no longer to be supported, it can be Retired by clicking the  icon to Change Approval State:

Choosing Retire retires the selected Version. Note that it is possible to re-publish a retired version through the same dialog.

Package Installations Requiring a Reboot

For installation packages that require a reboot of the device, the following guidance should be used when building the package.

1. An installer package or a package downloaded that uses a Post-Install command to install the package, the package itself should not reboot the device. This kind of action will interrupt the installation process and cause the package installation to fail. (Note: If the package is setup for multiple install attempts, the package will be dispatched again to the device because of the previous package installation failure.)
2. If a reboot is required, it should be setup as a Post-Install command. The command, script or program used should implement a “shutdown” command that will allow the device to properly notify the system and other applications that a system shutdown is in progress. By using this type of reboot process, it allows the package installation and other applications or running processes to shutdown properly. The use of a hard reboot command does not provide this type of graceful shutdown process and can potentially cause loss of data.

For more information on the use of shutdown commands available, call “shutdown /?” (Windows) or “shutdown --help” (Linux).

Package Examples

This section shows examples of some commonly installed applications, with the required Install Type for the package and Post-Install Command for the package.