1. Using Oracle Cloud Infrastructure Storage Software Appliance
  2. Managing the Appliance

7 Managing the Appliance

Topics

Changing the Admin Password for the Appliance

The admin password is required to log in to the management console of the appliance. You set the password while provisioning the appliance or while creating the first filesystem.

To change the admin password:
  1. Log in, using ssh, to the appliance instance, as the opc user:

    ssh opc@appliance_ip -i private_key

    • appliance_ip is the public IP address of the appliance instance. See Finding Out the IP Addresses of the Appliance Instance.
    • private_key is the full path and name of the file that contains the private key corresponding to any of the public keys that you specified in the appliance configuration file.
  2. Assume the root role: sudo su
  3. Go the /opt/oracle/gateway/gateway/admin/bin directory:
    cd /opt/oracle/gateway/gateway/admin/bin
  4. Run the following command:
    gateway password:reset
  5. Set the new password:
    gateway password:set new_password

    The password can contain from 8 to 32 characters, with at least one special character, one numerical character, one uppercase character, and one lowercase character.

Finding Out the IP Addresses of the Appliance Instance

The Oracle Cloud Infrastructure Compute Classic instance that hosts the appliance has two IP addresses: a fixed public IP address, and a private IP address that changes every time the instance is re-created or upgraded.

  • Use the public IP address to connect to the appliance instance using ssh, and to log in to the management console of the appliance.

  • Use the private IP address to mount the appliance filesystems on the client Oracle Cloud Infrastructure Compute Classic instances.

To find out the IP addresses of the appliance instance:

  1. On the host on which you downloaded the appliance provisioning tool, go to the directory that contains the tool, and run the following command:
    ./fscs.sh -i config_file
    In this command, config_file is the full path and name of the appliance configuration file.
  2. The tool prompts you to enter the password for the Oracle Cloud Infrastructure Compute Classic user specified in the configuration file. Enter the password.
    The tool validates the password and displays the IP addresses of the instance, as shown in the following example:
    Extracting IP addresses ...
Private IP address: 10.196.35.245
Public IP address: 203.0.113.48

Starting, Stopping, and Restarting the Appliance

When you provision the appliance using the provisioning tool, the appliance service and the management console are started automatically. You may need to stop and restart the appliance service or the management console in some situations.

The following are a few examples of the scenarios when such a restart may be necessary:
  • Prepare for a graceful shutdown of the appliance host
  • Maintain the appliance host
  • Suspend appliance operation
  • Recover from an issue, such as a hung management console

Important:

If you want to stop or restart the appliance host, then wait for any pending or ongoing write operations from the client instances to complete.
To stop, start, or restart the appliance, complete the following steps:
  1. Log in to your client instances using ssh and unmount the appliance filesystems before you stop or restart the appliance. (Example: umount /mnt/myFileSystem1)
  2. Log in, using ssh, to the appliance instance, as the opc user:
    ssh opc@appliance_ip -i private_key

    • appliance_ip is the public IP address of the appliance instance. See Finding Out the IP Addresses of the Appliance Instance.

    • private_key is the full path and name of the file that contains the private key corresponding to any of the public keys that you specified in the appliance configuration file.

  3. Assume the root role: sudo su
  4. Run the following command:

    • For Oracle Cloud Infrastructure Storage Software Appliance– Cloud Distribution Release 16.3.1.2 and 16.3.1.3:

      Syntax: 

      supervisorctl [stop | start | restart]  all

      Examples:

      • To stop the appliance: 
        supervisorctl stop all
      • To start the appliance: 
        supervisorctl start all
      • To restart the appliance: 
        supervisorctl restart all

    • For Oracle Cloud Infrastructure Storage Software Appliance– Cloud Distribution Release 16.3.1.0:

      Syntax: 

      supervisorctl -c /etc/supervisord/supervisord.conf [stop | start | restart]  all

      Examples:

      • To stop the appliance: 
        supervisorctl -c /etc/supervisord/supervisord.conf stop all
      • To start the appliance: 
        supervisorctl -c /etc/supervisord/supervisord.conf start all
      • To restart the appliance: 
        supervisorctl -c /etc/supervisord/supervisord.conf restart all
  5. Log in to your client instances and mount the appliance filesystems back to your mountpoints. See Mounting Appliance FileSystems on Client Instances.

Re-creating the Appliance

You may need to re-create the appliance instance when the instance is in an error state and you’re unable to recover from the error.

Note:

The appliance instance gets a new private IP address. So after the appliance is re-created, you must mount all the filesystems again on the client Oracle Cloud Infrastructure Compute Classic instances by using the new private IP address.

All the data disks are preserved. The appliance configuration settings, filesystem configurations, and data in the cache remain intact.

  1. Make sure that you have the appliance configuration file that you originally used to create the appliance.
  2. On the host on which you downloaded the appliance provisioning tool, go to the directory that contains the tool, and run the following command:
    ./fscs.sh -r config_file
    In this command, config_file is the full path and name of the appliance configuration file.
  3. The tool prompts you to enter the password for the Oracle Cloud Infrastructure Compute Classic user specified in the configuration file. Enter the password.
    The tool validates your credentials, and then does the following:

    1. Deletes the appliance instance.

    2. Creates the appliance instance.

    After creating the appliance instance, the tool displays the private and public IP addresses of the instances, as shown in the following example:
    Deleting Oracle Cloud Infrastructure Storage Software Appliance instance ... successful
Creating Oracle Cloud Infrastructure Storage Software Appliance instance ... successful
Extracting IP addresses ...
Private IP address: 10.196.35.245
Public IP address: 203.0.113.48
  4. Note the new private IP address.
  5. Mount the appliance filesystems on the client Oracle Cloud Infrastructure Compute Classic instances again. See Mounting Appliance FileSystems on Client Instances.

Adding Data Disks to the Appliance Instance

At any time, you can attach additional disks to the appliance instance to provide more local storage capacity that the appliance can use for caching data.

All the data disks that are attached to the appliance instance are combined into a resizeable logical volume group, named oracle_data_vg, which is mounted on the appliance instance at /opt/oracle/datadisk. When you add data disks, the oracle_data_vg volume group on the appliance instance is expanded to include the additional disks.

Caution:

The process of adding disks causes downtime for the appliance. The instance is deleted, the additional disks specified in the configuration file are created, a new appliance instance is created, and all the disks (including the new ones) are attached to the instance.

The appliance instance gets a new private IP address. So after the appliance is re-created, you must mount all the filesystems again on the client Oracle Cloud Infrastructure Compute Classic instances by using the new private IP address.

All the data disks are preserved. The appliance configuration settings, filesystem configurations, and data in the cache remain intact.

  1. Determine the additional storage capacity that you need for the appliance cache. See Best Practices – Configuring Cache Storage and Best Practices – Determining the Cache Size.
  2. In a text editor, open the appliance configuration file that you used originally to create the appliance.
  3. Under the storage attribute, add a datadisk subattribute for each disk that you want to add, as shown in the following example:
    Example:
        storage:
      - datadisk:
          name: /Compute-acme/jack.jones@example.com/myVol1
          size: 10G
          property: /oracle/public/storage/default
      - datadisk:
          name: /Compute-acme/jack.jones@example.com/myVol2
          size: 10G
          property: /oracle/public/storage/default
      - datadisk:
          name: /Compute-acme/jack.jones@example.com/myVol3
          size: 10G
          property: /oracle/public/storage/default
    You can attach up to nine data disks, each up to 2 TB in size.
    For more information about the parameters of the datadisk attribute, see Appliance Configuration Parameters.
  4. Validate the YAML format of the configuration file by using a tool such as YAML Lint (http://www.yamllint.com).

    Note:

    Oracle does not support or sponsor any third-party YAML validation tool.
  5. On the host on which you downloaded the appliance provisioning tool, go to the directory that contains the tool, and run the following command:
    ./fscs.sh -a config_file
    In this command, config_file is the full path and name of the appliance configuration file.
  6. The tool prompts you to enter the password for the Oracle Cloud Infrastructure Compute Classic user specified in the configuration file. Enter the password.
    The tool validates your credentials, and then does the following:

    1. Deletes the appliance instance.

    2. Creates the additional data disks that you’ve specified in the configuration file.

    3. Creates the appliance instance.

    4. Attaches all the data disks (including the new disks) to the appliance instance.

    5. Expands the oracle_data_vg volume group on the appliance instance to include the additional disks.

    After creating the appliance instance, the tool displays the private and public IP addresses of the instances, as shown in the following example:
    Adding new disks ...
Creating Oracle Cloud Infrastructure Storage Software Appliance instance ... successful
Extracting IP addresses ...
Private IP address: 10.196.35.235
Public IP address: 203.0.113.48
  7. Note the new private IP address.

    Tip:

    Retain a copy of the configuration file. You'll need it to run any further operations on the appliance.
  8. Mount the appliance filesystems on the client Oracle Cloud Infrastructure Compute Classic instances again. See Mounting Appliance FileSystems on Client Instances.

Upgrading the Appliance

You can upgrade your appliance to use the specific image by downloading it from the Oracle Cloud Downloads page at http://www.oracle.com/technetwork/topics/cloud/downloads/index.html. For the workflow to upgrade your appliance to the target release, see Upgrade Workflow.

When you upgrade the appliance instance, the binaries of the appliance are updated.

Caution:

  • The upgrade process causes downtime for the appliance. The appliance instance and its boot disk are deleted, a new boot disk is created (by using the image to which you want to upgrade the appliance), and the appliance instance is re-created using the new boot disk. Note that any OS-level changes you may have made on the boot disk of the appliance instance will be lost after the appliance is upgraded.

    The appliance instance gets a new private IP address. So after the appliance is re-created, you must mount all the filesystems again on the client Oracle Cloud Infrastructure Compute Classic instances by using the new private IP address.

    All the data disks are preserved. The appliance configuration settings, filesystem configurations, and data in the cache remain intact.

  • Ensure that you plan the downtime appropriately, as the upgrade may take some time. The downtime varies, depending on the system resources and if there are any filesystems to be restored from the cloud. If there are no filesystems to be restored, approximately 1 million records per minute may be transferred during migration, depending on the available system resources. If the filesystem needs to be restored from the cloud, then additional time would be required to download the metadata information and prepare the metadata database for migration.

    To minimize downtime, configure and connect the filesystems on the current appliance version before you upgrade the appliance.

Note:

Releases 16.3.1.2 and 16.3.1.3 include file system changes which require migration of filesystem internal data (metadata).
  • The migration takes place when your filesystems are reconnected for the first time to your storage service instance in the cloud during or after the upgradation.
  • Do not delete any filesystem or change the properties of a filesystem during the migration.
  • During the migration, all the filesystems are in the read-only state. After the filesystems are reconnected, the filesystems that had read / write permissions before the migration will return to the read / write state.
  •  The duration of the migration process is dependent on the size of the filesystem and can range from a few minutes to an hour or more.

Upgrade Workflow

Current Release of Your Appliance The Release that You Want to Upgrade Your Appliance To Steps Involved
16.3.1.0.13 16.3.1.3

Download the target image from the provided link and upgrade your appliance. See Steps to Upgrade the Appliance.

16.3.1.2 16.3.1.3
16.3.1.0 16.3.1.3

When you’re upgrading your appliance from release 16.3.1.0 to release 16.3.1.3, you must first upgrade it to release 16.3.1.0.13, and then upgrade it to your target release.

  1. Download the release 16.3.1.0.13 image from the provided link and upgrade your appliance. See Steps to Upgrade the Appliance.

    Ignore step 8.

  2. Download the target image from the provided link and upgrade your appliance. See Steps to Upgrade the Appliance.

Steps to Upgrade the Appliance

  1. Edit the appliance configuration file that you used to create the appliance, and update the image attribute to point to the new image that you obtained earlier.

    Example: 

    image: /Compute-acme/jack.smith@example.com/OSCSA-CD-image-v16.3.x.x

    To get a list of the available machine images, send the GET /imagelist/Compute-identity_domain/user HTTP request to your Oracle Cloud Infrastructure Compute Classic site. See REST API for Oracle Cloud Infrastructure Compute Classic.

    See Appliance Configuration Parameters.

  2. Validate the YAML format of the configuration file by using a tool such as YAML Lint (http://www.yamllint.com).

    Note:

    Oracle does not support or sponsor any third-party YAML validation tool.

  3. Log in to your appliance host, assume the root role, and stop the appliance.

    • If you want to upgrade your appliance from release 16.3.1.2:

      sudo su
supervisorctl stop all

    • If you want to upgrade your appliance from release 16.3.1.0.x:

      sudo su
supervisorctl -c /etc/supervisord/supervisord.conf stop all

  4. On the host on which you downloaded the appliance provisioning tool, go to the directory that contains the tool, and run the following command:

    ./fscs.sh -u config_file

    In this command, config_file is the full path and name of the appliance configuration file.

  5. The tool prompts you to enter the password for the Oracle Cloud Infrastructure Compute Classic user specified in the configuration file. Enter the password.

    The tool validates your credentials, and then does the following:

    1. Validates the name of the image that you’ve specified in the configuration file.

    2. Deletes the appliance instance.

    3. Deletes the boot disk that was created by using the old image.

    4. Creates a new boot disk by using the image that you’ve specified in the configuration file.

    5. Creates the appliance instance.

    This process may take a few minutes.

    After creating the appliance instance, the tool displays the private and public IP addresses of the instances, as shown in the following example:
    Creating Oracle Cloud Infrastructure Storage Software Appliance instance ... successful
Extracting IP addresses ...
Private IP address: 10.196.35.241
Public IP address: 203.0.113.48

    Tip:

    Retain a copy of the configuration file. You'll need it to run any further operations on the appliance.

  6. Note the new private IP address.

  7. Log in to the management console of your appliance using the public IP address.

    • If you’re upgrading your appliance from release 16.3.1.0.13 to release 16.3.1.3:

      After the metadata migration is complete, the following message appears on the dashboard for the respective filesystem: Migration completed. Please reconnect the filesystem.

      If your filesystem is connected to your storage service instance in the cloud, but you don't see the message about the completion of metadata migration, then wait for the migration to complete.

      If your filesystem isn’t connected to your storage service instance in the cloud, click Connect. Wait for the migration to complete.

      Disconnect and reconnect the filesystems after the migration is complete. See Connecting a FileSystem.

    • Otherwise:

      Connect your filesystems to the cloud service.

  8. Mount the appliance filesystems on the client Oracle Cloud Infrastructure Compute Classic instances again. See Mounting Appliance FileSystems on Client Instances.

Deleting the Appliance

When you no longer need the appliance or if you want to set up the appliance in a different Oracle Cloud Infrastructure Compute Classic site, you can delete the appliance and the Oracle Cloud Infrastructure Compute Classic instance hosting it. You can also choose to delete all the Oracle Cloud Infrastructure Compute Classic resources that are associated with the appliance instance.

Note:

Deleting the appliance has no effect on the data that was previously uploaded to your storage service instance in the cloud through the appliance. The containers and objects in your account remain intact.

Prerequisites

Wait for any pending or ongoing write operations from the client instances to complete.

Stop the appliance service and the management console from the appliance host:
sudo su
supervisorctl stop all

Steps for Deleting the Appliance

  1. Make sure that you have the appliance configuration file that you used to create the appliance.
  2. On the host on which you downloaded the appliance provisioning tool, go to the directory that contains the tool, and run the following command:
    • To delete only the appliance instance and retain its boot disk, data disks, and public IP address reservation:

      ./fscs.sh -d config_file

      You can use the same boot disk, data disks, and public IP address later when you want to create the appliance.

    • To delete the appliance instance as well as its boot disk, data disks, and public IP address reservation:

      ./fscs.sh -dd config_file

    In this command, config_file is the full path and name of the appliance configuration file.
  3. The tool prompts you to enter the password for the Oracle Cloud Infrastructure Compute Classic user specified in the configuration file. Enter the password.
    The tool validates the credentials and then deletes the appliance instance.
    After deleting the Oracle Cloud Infrastructure Compute Classic instance, the tool displays the following message:
    Deleting Oracle Cloud Infrastructure Storage Software Appliance instance ... successful
    If you used the -dd option, then the tool displays the following additional messages:
    Deleting boot disk ...  successful
Deleting data disks and IP reservation ...  successful