WeOS
5.29.0

# Media Tools

## Introduction

The system provides a number of simple tools to handle and maintain external media devices (e.g. USB, SD-Cards). External media devices can for instance be used for boot configuration and logging.

These media tools allows for simple partitioning and formatting of connected external media devices. Tools also exist for easy population of relevant files on external media along with synchronisation of files between medias.

For other related information see the following pages:

- System Bootstrap
- Config From External Media
- Access External Media Devices

## Overview

The media tools provided are quite limited in the uses that they provide. They aim to provide the possibility to perform the most basic type of operations directly on the device. For more extensive or advanced media operations it is recommended to use a PC. However, the provided tools should be able to handle most of the general use-cases that exist.

The following functionality is provided by the system, that acts directly on the connected external media device(s):

- Partition: Allows the user to partition and format a connected external media device in one simple step. It is possible to create up to four partitions. Each of these individual partitions will require a file system to be selected for the formatting that is performed at the same time. The limits to the formatting is the same as the stand-alone format option allows.

- Format: Allows the user to format a specific external media device with a file system and optional label. Currently one of the following file systems can be selected:

  - ext2
  - ext3
  - ext4
  - vfat, deprecated, see section filesystem.

The upcoming functions do not operate directly on the connected external media device itself. Instead they take a media definition as the selection variable. The operation can also only be used when the specified media definition is Active, i.e. the media definition matches a physical media device. The available functionality is as follows:

- Populate: Used to provide a factory configuration and default external media file structure to the specified media.

- Sync: Used to sync configuration files and certificates between two specified medias.

Note

Only one representation of the built-in flash currently exist named internal. All other media definitions that can be used are matched against externally connected media devices.

## Configuration

Media configuration tools are accessed from the admin execution context in the following manner:

    example:/#> media
    example:/media/#>

`format [DEV]`

  Format any connected physical media device (USB/SD-Card).

  Simple formatting of connected media device or partition. Allows to select the wanted filesystem and specification of an optional label.

  Note

  The command will enter a sub-context, see options in this context below.

  Warning

  Any files present on the selected device will be removed, once the formatting has been initiated. Therefore, make sure to backup any important files beforehand.

  Do not worry, the formatting will not begin until the `start-formatting` command is invoked in the actual format context, that is entered using this command.

  Example

      example:/media/#> format sdb1
      example:/media/format-sdb1/#> filesystem ext3
      example:/media/format-sdb1/#> label default
      example:/media/format-sdb1/#> show
      Format settings for device sdb1
      Filesystem : ext3
      Label      : default
      example:/media/format-sdb1/#> start-formatting

      Warning: Formatting this dev will remove any files currently stored on it!
               Backup any data you want to keep before formatting the dev.

      Do you still want to proceed (y/N)?y

      Formatting: 100% - [============================================================]

      Format successful!
      example:/media/#>

  `DEV`
    The physical media device to be formatted. This command is tab-completed for the available devices. Further, the available devices can be listed with the `show devices` command inside the media context.
`partition [DEV]`

  Partition any connected physical media device (USB/SD-Card).

  Easy setup of the partitioning of a connected media device. This includes defining each partition with a partition number, a size of the partition, an optional label and a fs to format the device with.

  Note

  The command will enter a sub-context, see options in this context below.

  Warning

  Any files present on the selected device will be removed, once the partitioning and formatting has been initiated. Therefore, make sure to backup any important files beforehand.

  Do not worry, the formatting will not begin until the `start-partitioning` command is invoked in the actual partition context, that is entered using this command.

  Example

      example:/media/#> partition sdb
      Entering partitioning mode with dev sdb as target…

      No changes will be performed until the start-partition command is
      invoked. When invoked the entire device sdb will be fully re-partitioned
      and re-formated, any files on the device will be LOST/REMOVED, keep
      this in mind before proceeding.

      example:/media/partition-sdb/#> delete all
      example:/media/partition-sdb/#> add label default size 50% format ext3
      example:/media/partition-sdb/#> add label my-files size 20% format ext3
      example:/media/partition-sdb/#> add size 20% format ext2
      example:/media/partition-sdb/#> add label example-folder size 10% format ext4
      example:/media/partition-sdb/#>
      example:/media/partition-sdb/#> show
      Partition table for dev: sdb
      #  DEV-NAME      PART-NUMB  LABEL                          SIZE      FS
      1  /dev/sdb1     1          default                        50%       ext3
      2  /dev/sdb2     2          my-files                       20%       ext3
      3  /dev/sdb3     3          -                              20%       ext2
      4  /dev/sdb4     4          example-folder                 10%       ext4
      example:/media/partition-sdb/#>
      example:/media/partition-sdb/#> start-partitioning

      Understand that the content on the device will be lost during the
      partitioning and formatting of the device. Make sure that the device
      does not contain any files that needs to be saved elsewhere.

      Start partitioning and formatting of the device (y/N)? y
      Attempt to delete existing partitions on device /dev/sdb:
        1: /dev/sdb1 [Partition numb: 1]
        2: /dev/sdb2 [Partition numb: 2]
        3: /dev/sdb3 [Partition numb: 3]
        4: /dev/sdb4 [Partition numb: 4]

      Attempt to partition device /dev/sdb in the following manner:
        1: /dev/sdb1 [Partition numb: 1], [Size: 50%]
        2: /dev/sdb2 [Partition numb: 2], [Size: 20%]
        3: /dev/sdb3 [Partition numb: 3], [Size: 20%]
        4: /dev/sdb4 [Partition numb: 4], [Size: 10%]

      Initiate formatting of the partitions, this may take a while:
        1: /dev/sdb1 [Partition numb: 1] [Label: default], format with ext3 FS…
      Formatting: 100% - [============================================================]

        2: /dev/sdb2 [Partition numb: 2] [Label: my-files], format with ext3 FS…
      Formatting: 100% \ [============================================================]

        3: /dev/sdb3 [Partition numb: 3] [Label: -], format with ext2 FS…
      Formatting: 100% \ [============================================================]

        4: /dev/sdb4 [Partition numb: 4] [Label: example-folder], format with ext4 FS…
      Formatting: 100% \ [============================================================]

      Device sdb successfully partitioned and formatted!
      example:/media/#>

  `DEV`
    The physical media device to be formatted. This command is tab-completed for the available devices. Further, the available devices can be listed with the `show devices` command inside the media context.
`populate [MEDIA]`

  Populates external media with factory config and directories for certificates.

  Example

      example:/media/#> populate external

  `MEDIA`

    Dynamically created using the `media` command in the boot configuration context. Use the `show` command in the current context to list all existing media definitions. All usable media definitions will be listed under Active. In addition, two default media definitions exist if no changes have been made to medias in the boot context:

    - `internal:` The representation of the built-in flash. This cannot be changed or removed.

    - `external:` The default media definition for any connected external media device (e.g. USB, SD-Card). It is configured to always match the first partition on said external media device. This definition is not static or locked, it can be freely adjusted by the user, even removed.

`sync [FROM]<MEDIA> [TO]<MEDIA>`

  Sync configuration and certificates between media.

  Copies configuration and certificates from the `FROM`, media if any, to the `TO` media. If no `FROM` media is specified the currently used media based on the active boot config is chosen.

  Example

      example:/media/#> sync internal external
      Syncing may remove .cfg and certificate files from destination media.
      Are you sure you want to continue (y/N)? y
      example:/media/#>

  `MEDIA`

    Dynamically created using the `media` command in the boot configuration context. Use the `show` command in the current context to list all existing media definitions. All usable media definitions will be listed under Active. In addition, two default media definitions exist if no changes have been made to medias in the boot context:

    - `internal:` The representation of the built-in flash. This cannot be changed or removed.

    - `external:` The default media definition for any connected external media device (e.g. USB, SD-Card). It is configured to always match the first partition on said external media device. This definition is not static or locked, it can be freely adjusted by the user, even removed.

`eject [force] [MEDIA]`

  Eject (unmount) a connected external media device.

  Try to safely unmount and eject the specified media device. If no specific media is specified the currently active media(s) will be ejected (except the internal media).

  Not ejectable

  The internal media cannot be ejected.

  Example

  Eject a specific media:

      example:/media/#> eject external
      Are you sure you want to eject media ‘external’ (y/N)? y
      Media ‘external’ ejected successfully.
      example:/media/#>

  Eject all active media:

      example:/media/#> eject
      Are you sure you want to eject all active media (y/N)? y
      Media ‘external’ ejected successfully.
      example:/media/#>

  `force`
    If specified the media will try to be unmounted regardless if it is busy or not. This may lead to data loss on the media.
  `MEDIA`

    Dynamically created using the `media` command in the boot configuration context. Use the `show` command in the current context to list all existing media definitions. All usable media definitions will be listed under Active. In addition, two default media definitions exist if no changes have been made to medias in the boot context:

    - `internal:` The representation of the built-in flash. This cannot be changed or removed.

    - `external:` The default media definition for any connected external media device (e.g. USB, SD-Card). It is configured to always match the first partition on said external media device. This definition is not static or locked, it can be freely adjusted by the user, even removed.

`mount-inactive`

  Try to mount all inactive media defined in the boot configuration.

  When a media is inactive it has been defined as a media in the boot configuration but is not currently mounted. This command will try to mount all such media.

  Generally an inactive media should be mounted on a hotplug event of the media device. This command is provided as a way to manually mount any inactive media if needed.

  Mounting internal media

  The internal media is always mounted and cannot be mounted again.

  Example

      example:/media/#> mount-inactive
      Attempting to mount 1 inactive media…
      Media ‘external’ mounted successfully.
      example:/media/#>

`mount-available [DEV]`

  Try to mount available media device(s).

  When a media device is available it means that there is a physical device connected to the system. This command will try and mount all or a specified device to a media defined in the boot configuration. In other words, a defined media that is listed as inactive must be present in order for there to be a possibility to mount it. Hence, it must still be defined in the boot configuration, this command simply tries to mount the device based on the match rules defined for a given media definition.

  Generally an available media should be mounted on boot or on a hotplug event of the media device. This command is provided as a way to try manually and mount any available media if needed.

  Example

  Try to mount any available media:

      example:/media/#> mount-available
      Device ‘sda1’ mounted successfully on media ‘external’.
      example:/media/#>

  Try to mount a specific device:

      example:/media/#> mount-available sda1
      Device ‘sda1’ mounted successfully on media ‘external’.
      example:/media/#>

  `DEV`
    The physical media device to be mounted. This command is tab-completed for the available devices. Further, the available devices can be listed with the `show devices` command inside the media context.

### Format Settings

The format configuration tool is a sub-context of the media context:

    example:/media/#> format sdb1
    example:/media/format-sdb1/#>

Note

In the format context you create the intended formatting setup for the device. None of the commands will perform any direct changes on the device. Only when the `start-formatting` command is called will any actual changes be performed on the selected device.

`[no] filesystem [FS]`

  Select desired filesystem to format on the selected device.

  `no`
    A file system must be selected, it can only be changed not removed.
  `FS`

    The wanted filesystem selectable from the following types:

    - `ext2`
    - `ext3`
    - `ext4`
    - `vfat`, deprecated, see below.

  Note

  VFAT is deprecated and is not fully supported. Certificates cannot be imported on external media formatted with VFAT.

`[no] label [LABEL]`

  Set optional label to be used on the formatted device.

  `no`
    Remove any configured label. It is fine to have a file system that has no configured label.
  `LABEL`

    Free-form string of the wanted label for the file system. The allowed max length of the label may depend on the file system selected. If it is to long for a particular file system the name may be automatically trimmed.

    Note

    A label is not required, it is valid to not have a label.

`start-formatting`

  Start formatting the device according to current configuration.

  Before this command is invoked no changes will be made to the selected device. If the formatting context is exited and this command has not been called, the device will retain its previous formatting configuration.

  Warning

  When this command is invoked and the formatting of the device commence, all files currently present on the device will be removed. Ensure that any file that should be saved have been so.

### Partition Settings

The partition configuration tool is a sub-context of the media context:

    example:/media/#> partition sdb
    example:/media/partition-sdb/#>

Note

In the partition context you create the intended structure of the wanted partitions. None of the commands will perform any direct changes on the device. Only when the `start-partitioning` command is called will any actual changes be performed on the selected device.

`add [part-numb NUMB] [label LABEL] [size SIZE] [format FS]`

  Add a new partition definition.

  `part-numb`

    The wanted partition number for the partition, specified by `NUMB` and must be between 1-4.

    Note

    If not specified the lowest available partition number will be used.

    Note

    Multiple partition definitions cannot have the same partition number.

  `label`

    The wanted label for the filesystem to be formatted on the partition.

    `LABEL`

      Free-form string of the wanted label for the file system. The allowed max length of the label may depend on the file system selected. If it is to long for a particular file system the name may be automatically trimmed.

      Note

      A label is not required, it is valid to not have a label.

  `size`

    The wanted size of the partition, specified by `SIZE`.

    `SIZE`

      The size of the partition, specified by a numerical value and a value indicator: K, M, G or %.

      Examples: 1000K, 20M, 1G or 50%

  `format`

    The wanted filesystem to be formatted on the partition.

    The format can be selected from the values specified by `FS`.

    `FS`

      The wanted filesystem selectable from the following types:

      - `ext2`
      - `ext3`
      - `ext4`
      - `vfat`, deprecated, see section filesystem.
`modify INDEX [part-numb NUMB] [label LABEL] [size SIZE] [format FS]`

  Modify an existing partition definition.

  `INDEX`
    The index of the partition definition to modify.
  `part-numb`

    The wanted partition number for the partition, specified by `NUMB` and must be between 1-4.

    Note

    If not specified the lowest available partition number will be used.

    Note

    Multiple partition definitions cannot have the same partition number.

  `label`

    The wanted label for the filesystem to be formatted on the partition.

    `LABEL`

      Free-form string of the wanted label for the file system. The allowed max length of the label may depend on the file system selected. If it is to long for a particular file system the name may be automatically trimmed.

      Note

      A label is not required, it is valid to not have a label.

  `size`

    The wanted size of the partition, specified by `SIZE`.

    `SIZE`

      The size of the partition, specified by a numerical value and a value indicator: K, M, G or %.

      Examples: 1000K, 20M, 1G or 50%

  `format`

    The wanted filesystem to be formatted on the partition.

    The format can be selected from the values specified by `FS`.

    `FS`

      The wanted filesystem selectable from the following types:

      - `ext2`
      - `ext3`
      - `ext4`
      - `vfat`, deprecated, see section filesystem.
`delete [INDEX] [all]`

  Delete a specifc or all existing partition definitions.

  `INDEX`
    The index of the partition definition to delete.
  `all`
    If specified all current partition definitions will be removed.
`start-partitioning`

  Start partitioning and formatting the device according to current configuration.

  Before this command is invoked no changes will be made to the selected device. If the partitioning context is exited and this command has not been called, the device will retain its previous partitioning configuration and formatting.

  Warning

  Understand that the content on the device will be lost during the partitioning and formatting of the device. Make sure that the device does not contain any files that needs to be saved elsewhere.

## Status Overview

Using the `show` command in media context will show an overview of our media devices:

    example:/#> show media
    MEDIA       DEVICE      LABEL          FORMAT   RW     SIZE  USED  DESCRIPTION
    Active
    internal    mtd:Config  -              jffs2    Yes   15.0M    5%  config,cert
    external    sdb1        default        ext3     Yes    1.8G    0%  logging
    Inactive
    my-logs     -           -              -        -         -     -
    Available
    -           sdb2        my-files       ext3     -    764.0M     -
    -           sdb3        -              ext2     -    764.0M     -
    -           sdb4        my-label       ext2     -    100.0M     -

This view allows the user to immediately gain an understanding of how any connected external media relates to the media definitions. For any external media to be made available on the system, a media definition has to be created to match a specific physical media device or a partition on the device. For more information how this is achieved refer to the Access External Media Devices page.

However, the basic meaning for each of the sub-headers in the output are as follows:

- `Active`: A media definition that has a matching physical media device, and is as such Active and available to the user in the system. The `internal` media definition is a special case that represents the built-in flash media. All other created media definitions intend to match against a connected external media device.

- `Inactive`: Media definitions, that have been created but currently have no matching external media device connected, will be listed here. For instance, any media definition would be listed here in case no external media device have been physically connected to the device. Hence, in this case they are Inactive since no physical device exist that match the media definition.

- `Available`: Any physical connected external media that is not matched with a media definition will be listed here. They are available and need to be matched against a media definition to become Active and available in the system.

It is also possible to list information strictly related to the status of the connected external media device(s), using the `show devices` command in the media context:

    example:/#> show media devices

    Connected Media Devices
    NAME      TYPE  NUM  LABEL                      FORMAT   SIZE     MOUNT-MEDIA
    sdb       disk  -    -                          -        3.7G     -
      sdb1    part  1    default                    ext3     1912M    external
      sdb2    part  2    my-files                   ext3     764M     -
      sdb3    part  3    -                          ext2     764M     -
      sdb4    part  4    my-label                   ext2     100M     -

« Previous Next »