Welcome to MetalSoft’s documentation!

Note that this version of the documentation applies to an older version (6.x and prior) of our software. Refer to the latest documentation for the more up to date information.

MetalSoft is an intelligent bare metal automation software platform for managing data centers and equipment, from a single rack of servers or tens of thousands across the globe.

The MetalSoft Platform

• Getting started
  • Architecture
    • Network topology
      • Data plane logical network topology
      • Gateway management
        • MetalSoft-managed gateways
        • Externally managed gateways
    • User interfaces
      • Administrative interface
      • End-User interface
  • Deploying MetalSoft
    • Deployment Overview
      • Hardware/Cabling Requirements
      • Installation of the MetalSoft Global Controller
      • Installation of the MetalSoft Site Controller
      • Check Connectivity
      • Create Datacenter Record
      • Create Users/Accounts
      • Register Switch templates (if applicable)
      • Create Subnets
      • Register Switches
      • Register Servers
      • Register Storage (If applicable)
      • Register OS templates
      • Set up network profiles (if applicable)
      • Test deployment of OS in Infrastructure Editor
      • Summary
    • Physical topology
      • Production rack cabling guide - No storage
      • Production rack cabling guide - data & storage fabrics on the same physical leaf switches
      • Production rack cabling guide - separate data & storage fabrics
      • Control plane (Management network) architecture
        • Bare metal Site Controller cabling
        • Virtual Site Controller, L2 connectivity
        • Virtual Site Controller, L3 connectivity
        • Site Controller cabling - PXE (legacy, deprecated)
    • Kubernetes cluster compute requirements
      • Minimum Requirements
      • Recommended Requirements
        • Master nodes
        • Worker nodes
      • Storage Best Practice
    • Deploying the MetalSoft Global Controller
      • Kubernetes cluster compute requirements
      • Other requirements
      • Installing the MetalSoft controller kubernetes application
      • Required controller firewall configuration
        • Ports open for inbound from Site Controllers
        • Ports open for inbound from clients
        • Outbound traffic
          • For Firmware Upgrades:
          • For pulling ISO files, can be hosted on customers own http storage:
          • For installing/upgrading Kubernetes:
          • For pulling MetalSoft images at installation/upgrade time:
          • For pulling standard images at installation/upgrade time:
          • Mail Server requirements If using Office365 for email alerts:
          • For base OS package updates:
          • For installing kubernetes
      • Inter-cluster traffic
    • Deploying the MetalSoft Site Controller
      • Resource requirements
      • Other requirements
      • Bare metal Site Controller cabling
      • Virtual Site Controller, L2 connectivity
      • Virtual Site Controller, L3 connectivity
      • Install the Datacenter Site Controllers on the DC Site Controllers machine
        • Automated Install
      • Site Controller firewall configuration
        • Ports open to inbound connections for virtual-media-based deployments
        • Ports open to inbound connections for zero-touch
        • Outbound traffic
        • In-Band Access - Outbound from the Site Controllers perspective
    • Deploying MetalSoft in an air gapped environment
      • Repository requirements
      • Internal Firewall Rules
        • Global Controller
        • Site Controller
      • Installation of the Global and Site Controller
      • Installation of the OVA VM’s in an air gaped environment
      • Upgrading the OVA VM’s in an air gapped environment
        • Global Controller Upgrade with provided packages
        • Site Controller Upgrade with provided packages
        • Global Controller Upgrade with selected images
        • Site Controller Upgrade with selected images
    • Setup of MetalSoft Kubernetes Cluster on K3S
      • Base setup
        • Install Helm:
        • Install MetalLB:
      • MetalSoft Setup
      • Manual steps for MetalSoft Setup if required
        • Add SSL certificate to Kubernetes cluster
          • To add the certificate to secrets.yaml
          • To add the key to secrets.yaml
        • Generate encryption keys in the Kubernetes cluster
        • Initiate the MetalSoft setup:
        • Install Debug utilities:
      • Check the state of the setup
    • Using the CLI
      • Installation
      • Getting the API key
      • Getting a list of supported commands
      • Getting started
      • The kubernetes-style ‘apply’ functionality
      • Condensed format
      • Using label instead of IDs
      • Permissions
      • Debugging information
      • Building the CLI
        • Updating the SDK
    • Registering switches via Zero Touch Provisioning (ZTP)
      • How the ZTP process works
        • ONIE-based process
        • To manually set a compatible switch in ONIE mode
      • Cisco ACI ZTP process
      • Variable glossary
    • Registering servers via Zero Touch Provisioning (ZTP)
    • Deploying MetalSoft to support legacy (PXE) deployments
      • Cabling
      • IP Allocation
      • Router configuration
      • Switch configurations
        • Out-of-band (OOB) Switch configuration
        • Top-of-Rack (ToR) switch configuration
      • Register (enroll) a switch
      • Pre-flight checklist
      • Configuring configuration for SSL enabled repository access
    • Deploying MetalSoft using OVAs
      • Download the images
      • Installing & configuring the Global Controller VM
        • 1. Deploy the Global Controller Appliance VM in ESXi
        • 2. Configure the IP of the Global Controller image
        • 3. Setup a hosts file entry or a DNS record
        • 4. Access the Global Controller
      • Installing & configuring the Site Controller VM
        • Configure the IP of the Site Controller
      • Connecting the Site Controller to the Global Controller
      • Next steps
      • Restricted internet access
      • Restarting the agents
    • Deploying MetalSoft without switches
      • Environment configuration
      • Create the datacenter:
      • Create WAN subnets
      • Create OOB subnet
      • Create a “dummy” switch
      • Deploy the MetalSoft Site Controller
    • Enabling end-users to create custom RAID configurations
    • Enabling traffic accounting
      • Redundancy, scalability and accuracy
  • Troubleshooting and Maintenance
    • Troubleshooting deploys using the Operation’s Graph (AFC tree)
    • Troubleshooting server registrations using the Operation’s Graph (AFC tree)
    • Event log archiving via Kafka
    • Managing custom ISO’s
      • To list custom ISO’s:
      • To create a custom iso:
      • To modify a custom iso
      • To delete a custom iso:
      • To boot a server from a custom ISO
      • To create a custom ISO
    • Post upgrade testing
      • User Management
        • Create new user
        • Create new user with admin role and ensure when logging in, user is directed to Admin UI
        • Send password recovery e-mail
        • Resend invitation e-mail
        • Block or Suspend a user
        • Check “forgot password” function on login page
        • If enabled, Check Sign up
      • Server Management
        • Test server can be powered on and off in the Admin UI
        • Re-register available server
        • Delete and register available server
        • Check VNC console works from Admin UI for a used server
        • Check Custom ISO boot works (combined Server Management/Infrastructure Editor)
      • Infrastructure Editor
        • Test deployment of instance array
        • If available, test deployment of drive array
        • If available, test deployment of shared drive
        • Check if a user can be added as a delegate to a deployed Infrastructure
        • Check VNC console works from Instance
    • Kubernetes cluster certificate management
      • Checking if certificates have expired
      • Renewing Kubernetes certificate
      • Check pods and certificate
  • How to backup MetalSoft
    • Enabling the automatic backup of the databases
    • Parameters for the backup script
  • How to enable Disaster Recovery for MetalSoft
    • RPO and RTO
    • Steady state:
    • Failover state:
    • Sync procedure
    • Triggering the failover
    • Testing the failover
  • Release notes
    • Version 6.4 - January 28, 2025
    • Version 6.3.3 - September 30, 2024
    • Version 6.3.2 - August 30, 2024
    • Version 6.3.1 - August 1, 2024
    • Version 6.3 - June 29th, 2024
    • Version 6.2.1 - March 18, 2024
    • Version 6.2 - February 1, 2024
    • Version 6.1 - November 8, 2023
    • Version 6.0 - June 12, 2023
    • Version 5.3 - 1st of May 2023
    • Version 5.2 - 6 January 2023
    • Version 5.1 - 23 January 2023
    • Version 5.0 - 4 November 2022
    • Version 4.10.1 - 25 July 2022
    • Version 4.10 - 24 may 2022
    • Version 4.9 - 15 December 2021
    • Version 4.8.2 - 15 July 2021
    • Version 4.8.1 - 30 March 2021
    • Version 4.8 - 03 March 2021
    • Version 4.7 - 17 December 2020
    • Version 4.6 - 26 October 2020
    • Version 4.5 - 12 August 2020
    • Version 4.4 - 9 July 2020
    • Version 4.1 - 21 April 2020
    • Version 4.0 - 12 March 2020
• Configuration
  • Users and permissions
    • Authentication Overview
      • The Role parameter
      • The login flow
      • 2Factor (MFA) authentication
    • Managing users and permissions
      • User accounts
      • Role based access control (RBAC)
      • Users related permissions
        • Network profiles
      • Licenses related permissions
      • Firmware related permissions
      • Datacenter related permissions
      • Servers
      • Switches
      • Storage
      • IPAM Subnets
      • Infrastructures
      • OS Templates
      • Events & jobs
      • Workflows
      • Prices & Subscriptions
      • Reports
      • Utility
      • Deprecated permissions, do not use
      • Resource ownership
      • The “Billable” account
      • Credentials access - DEPRECATED
      • User limits
      • Suspend and unsuspend a user
      • Block and unblock user
      • Archiving an user
      • Delegation
        • Example scenario
        • Managing account delegation
        • Managing infrastructure delegation
    • Configuring LDAP authentication for Microsoft Active Directory
    • Configure SAML for OKTA
      • Step 1. Configuring Okta
      • Step 2. Configuring MetalSoft App for using Okta configuration.
    • Managing Resource Pools
      • Creating a subnet pool
      • Allocating servers to a resource pool
      • Allocating subnet pools to a resource pool
    • Managing accounts
      • Creating an account
      • Adding a user to an account
  • Data centers
    • Adding a new datacenter
      • Creating a datacenter record using the UI
      • Creating a datacenter record using the CLI
      • Updating a datacenter configuration using the CLI
  • Networking
    • Networking overview
      • Important concepts of MetalSoft networking
      • An example setup
        • User-level Intent configuration
        • Admin-level configuration
      • How abstract operations define intents
      • MetalSoft Networks
      • MetalSoft Network profiles
      • Details on link-aggregation
      • How server interface indexes are allocated
      • OS Interface Index
      • Virtualization networking
    • Managing switches
      • Getting switch details using the CLI
      • Adding a switch using the CLI
      • Listing switches using the CLI
      • Editing switch configurations using the CLI
      • Deleting a switch using the CLI
      • Creating switch pairs
      • Operating without switches
    • Switch replace
      • Switch with ZTP support
      • Switch without ZTP support
    • Managing switch pairs
      • Create a switch pair
      • Listing switch pairs
      • Deleting switch pairs
    • IP address Management (IPAM)
      • How does it work?
      • WAN Subnets
        • Adding a WAN subnet
        • When are subnets allocated?
        • When are subnets freed?
      • WAN Gateways
      • Custom VLAN IDs and Subnets
      • Secondary IPs vs Primary IPs
      • Adding a new subnet pool using the CLI
      • Virtual Routing and Forwarding - VRFs
        • Creating a VRF
      • Adding a VRF-VLAN mapping
    • Managing network profiles
      • Creating a new network profile
        • Configuring a custom access mode VLAN for the switch ports
        • Allowing a VLAN ID to be trunked on the port
        • Specifying a custom subnet for a trunked VLAN
        • Extending a VLAN id to an External Connection on a border device
        • Aggregating links into M-LAG or LAG groups
        • Using a member of a link aggregation without link aggregation configured
        • Example configuration
      • Adding a network profile using the Admin UI
        • Creating a network profile with the cli:
        • Listing the existing network profiles:
      • Network profiles permissions
      • Auto-allocation VLAN IDs
      • VRFs
    • Adding a new external connection
    • Adding Cisco ACI APIC Switches in a new datacenter
      • Creating the datacenter
      • Adding ACI Switch Controller
        • Using UI
        • Using metalcloud-cli
        • Adding Shared VRF using metalcloud-cli
      • Add WAN subnet pool
      • Add OOB subnet pool.
    • Enabling Secondary IPs and/or VLANs on the WAN interface
      • Configuring the secondary interface in the kickstart file of the template
    • EVPN VXLAN network provisioner
      • Network profiles
      • Gateway management
      • VRFs
      • VRF dedicated VLANs/VNIs
  • Servers
    • Servers overview
      • Lifecycle stages
      • General guidelines when registering servers
        • Determining cabling and other hardware issues
      • Registering servers that cannot be touched
      • Troubleshooting a stuck server registration process
        • Server lifecycle
          • Server states
          • Interact with the server states
          • Server cycles
        • Managing hardware failures and changes
          • No Re-Registration required (but advised)
          • Network card changes
          • BMC board/Motherboard changes
          • Upgrading a server
        • Server types
          • Creating a new server type
          • Allocating a server type to a server
        • Adding a new server
        • Adding a new managed server
          • Adding a new managed server via the Add Server button
          • Adding a new managed server via the CLI
          • Adding a new server via Zero Touch
          • Default RAID configuration
        • Re-registering a server
        • Adding a new un-managed server
          • Adding a new un-managed server using the UI
          • Adding a new un-managed server via the CLI
          • Fields accepted
        • Managing server firmware
          • Mass firmware upgrades
          • Upgrading a server’s individual components
          • Enabling automatic firmware upgrades
        • Managing firmware catalogs
          • Preparing an HTTP repository
          • Configuring the CLI for managing firmware catalogs and firmware binaries
            • Repository-related variables
            • User-related variables
            • HP-related variables
          • Creating a firmware catalog record and uploading binaries
            • Dell example
            • CLI firmware-catalog create command behavior
            • Customizing a catalog
          • Vendor specific details
          • Periodic update
        • Managing Firmware baselines
          • Creating a firmware baseline
          • Editing a baseline
          • Removing a baseline
    • Server lifecycle
      • Server states
      • Interact with the server states
      • Server cycles
    • Managing hardware failures and changes
      • No Re-Registration required (but advised)
      • Network card changes
      • BMC board/Motherboard changes
      • Upgrading a server
    • Server types
      • Creating a new server type
      • Allocating a server type to a server
    • Adding a new server
    • Adding a new managed server
      • Adding a new managed server via the Add Server button
      • Adding a new managed server via the CLI
      • Adding a new server via Zero Touch
      • Default RAID configuration
    • Managing BIOS settings
    • Re-registering a server
    • Adding a new un-managed server
      • Adding a new un-managed server using the UI
      • Adding a new un-managed server via the CLI
      • Fields accepted
    • Managing server firmware
      • Mass firmware upgrades
      • Upgrading a server’s individual components
      • Enabling automatic firmware upgrades
    • Managing firmware catalogs
      • Preparing an HTTP repository
      • Configuring the CLI for managing firmware catalogs and firmware binaries
        • Repository-related variables
        • User-related variables
        • HP-related variables
      • Creating a firmware catalog record and uploading binaries
        • Dell example
        • CLI firmware-catalog create command behavior
        • Customizing a catalog
      • Vendor specific details
      • Periodic update
    • Managing Firmware baselines
      • Creating a firmware baseline
      • Editing a baseline
      • Removing a baseline
  • Storage
    • Adding a new storage pool
      • Adding a new storage pool
    • Storage Appliances Prerequisites
      • Dell PoweScale
        • Enable API
    • Managing storage pools
      • Putting a storage pool in maintenance mode
      • Performing an emergency reboot of all connected servers
      • Cleaning up unused templates
  • Operating System Templates
    • Managing Operating System templates
      • Listing available source templates
      • Registering a new template
      • Checking if the template has been registered:
      • Customizing a template
      • Upgrading an existing template to a newer version
      • Building a new template from scratch
      • Building a new source template for legacy systems
    • Template language and variables
      • Example usage
      • Reference
      • Example objects and their content
    • Advanced OS deployment configurations
      • Enabling the virtual media based deploy mechanism and configuring it as default
      • Enabling the legacy PXE-based deploy mechanism and configuring it as default.
    • Managing OS templates for legacy deployment process (PXE)
      • An example install process
      • Creating a new OS template using the CLI
        • Choosing an architecture
      • Specifying a bootloader and config file
      • Specifying a custom config for iPXE
      • Associating assets with OS Templates
      • Important variables
    • OS templates simple asset template variables glossary (DEPRECATED)
      • Infrastructure variables
      • Pre-deploy stage variables
      • Post-deploy stage variables
      • Instance Array variables
      • Instance variables
      • IPv6 Variables
      • Drive Array variables
        • Deprecated drive array iSCSI options
      • Shared Drives
      • SNMP variables
      • Datacenter variables
      • Quarantine variables
      • General purpose variables
    • JSON Schema
      • Definitions
    • How to add boot and install drivers to a repository Windows ISO
  • Resource Pools
    • Managing resource pools
      • Creating a resource pool
      • Deleting a resource pool
      • Assigning a server to a resource pool
      • Moving a server from a resource pool to another
      • Removing a server from a resource pool
      • Adding a subnet pool to a resource pool
      • Moving a subnet pool from a resource pool to another
      • Removing a subnet pool ver from a resource pool
      • Assigning resource pools to users
      • Unassign a resource pools for a user
  • Monitoring
    • Syslog forwarding and alerting
      • To configure alerting rules
      • Connecting an external event monitoring system to the kafka queue.
  • Virtualization
    • Managing VM Pools
      • Registering a VM Pool
      • VM Types
      • VM Images
      • Creating a custom repository for images
      • Listing the hosts of a VM Pool
      • Listing VMS
      • Rebooting a VM or accessing the console
    • Managing VMs
      • Creating a VM Array
      • Virtual networking
      • Accessing the console of a VM
• ELI
  • ELI - AI assisted diagnosis overview
    • Getting the switch ports of a switch
    • Getting the VLANs configurations on a switch
    • Getting BGP Sessions status of a switch
    • Getting LLDP neighbors of a switch
    • Using the topology information
• Operation
  • Getting started
  • Concepts
    • Important concepts
    • Instance Arrays and Drive Arrays
    • Infrastructures
    • Servers and Instances
  • Managing infrastructures
    • Creating an infrastructure using the UI
    • Creating an infrastructure using the CLI
    • Listing infrastructures using the CLI
    • Changing an infrastructure’s properties using the UI
    • Deleting an infrastructure using the CLI
  • Managing instance arrays
    • Deploying an instance array using the Infrastructure Editor
    • Retrieving server access credentials using the UI
    • Deploying an instance array using the CLI
    • Retrieving server access credentials using the CLI
    • Checking the power status of all the instances in this instance array using the CLI
    • Rebooting an instance using the CLI
  • Managing networks
    • Using multiple links
    • Joining an existing network
    • Creating a LAN network
    • Advanced: Subnet pools
    • Advanced: Network profiles
      • To create a network profile as a user
      • To add additional trunk mode vlans to the same network profile
  • Managing drive arrays
    • Creating a drive array using the UI
    • Listing drive arrays of an instance array using the UI
    • Adding a new drive
    • Removing a drive
    • Expanding disk size
    • Creating a drive array using the CLI
    • Listing drive arrays of an infrastructure using the CLI
    • Deleting a drive array via the CLI
    • Manually logging into the iscsi target
  • Deploying Kubernetes on MetalSoft
    • Deploying Kubernetes using the UI:
      • Configure the node server types and count
      • Accessing the cluster
    • Setting up a sample application on Kubernetes
      • Deploying RedHat OpenShift, Rancher or other distributions of Kubernetes on MetalSoft
        • MetalSoft automatic DNS management
  • Using the CLI
    • Installation
    • Getting the API key
    • Getting a list of supported commands
    • Getting started
    • Kubernetes-style Apply support
    • Condensed format
    • Using label instead of IDs
    • Permissions
  • Connecting to linux servers through SSH
    • Locating access credentials and connecting
  • Connecting to Windows servers through RDP
    • Locating access credentials
    • Connect to your server via RDP.
    • Locate your RDP Rule
    • Creating Your IP Restrictions
  • Delegating access to an infrastructure
  • Retrieving the utilization report
    • The Detailed utilization report
    • Viewing server subscriptions (reservations)
  • Configuring a custom RAID profile
  • Enabling two factor authentication (2FA) in Metalcloud
  • Manually managing iSCSI connections
    • Retrieving the drive array’s connection details from the UI
    • Retriving iscsi access credentials using the CLI
    • Logging into the iSCSI target from Linux (CentOS/Redhat)
    • Logging into a drive on Windows using PowerShell
    • Prepare and format disk in Powershell
    • Disconnect from all iscsi targets in Windows using Powershell Or Just disconnect Offline target
    • Disable indexing on a drive in Powershell
  • Setting delegation for reseller scenarios
    • Setting up users and permissions in a referral scenario when end-users own the infrastructures
    • Setting up users and permissions in a fully managed reseller scenario
    • Setting up users and permissions in a reseller scenario when end-users have access to infrastructures
  • Forcing specific servers at deploy
• Developer resources
  • Developer Getting Started
  • Connecting to the API
    • The API endpoint:
    • Retrieving my API key and connecting to the endpoint
    • API Reference
    • Authenticating to the API
      • Interacting with the API
        • Authenticating to the API
        • Object Schemas
        • IDs and labels
        • Decrypting credentials
  • Callbacks and post-install operations
    • Using Workflows to call outside systems
      • Add a deployment finished callback
        • Create an HTTP task for callback
        • Create a global workflow and add the task
      • Customizing operating system templates behavior
        • How OS deployment works
        • Changing the unattended install file
  • Using the Terraform provider
    • Using the Provider
  • Building a CI/CD pipeline
  • Integrating with a customer portal
    • Direct integration with an upstream customer portal
      • SAML-compatible ID service (Recommended)
      • LDAP-compatible ID service
      • Built-in authentication
        • Managing users via the API
        • Enabling user sign-up
    • Indirect integration with an upstream customer portal
    • Embedding the MetalSoft Remote Console into a customer portal
  • Embedding the remote console
    • Main components
    • Key Requirements:
  • Integrating with a Billing System
    • Making the API call
    • Using the subscriptions
    • Using the pricing information
  • Workflows
    • Managing workflows
      • Workflow execution contexts
      • Workflow usages
      • Creating a workflow
      • Listing workflows
      • Adding stages to a workflow
      • The behavior of WorkflowReference in instance array contexts
      • Workflow Variables
    • Managing workflow tasks
      • HTTP Request tasks
        • HTTPRequest cookie jar
      • Ansible Bundle workflow tasks
        • Ansible Bundle inventory file
        • Additional variables
        • How ansible gets executed
      • WorkflowReference stages
      • Listing stages
    • Managing variables and secrets
      • Referencing variables
      • Referencing secrets
      • Creating a variable from console input
      • Creating a variable using a pipe
      • Creating a secret from user input
      • Creating a secret from pipe
    • Using infrastructures with workflows
      • Attaching workflows
      • Empty infrastructures
      • Attaching a workflow to a instance array
      • Specifying certain server IDs
    • Sample workflow - Automatically adding a host to an external VMWare VCenter
      • Creating a Task for enroll into vCenter
      • Create a workflow
      • Add stages to workflow
      • Verify the stages
      • Add workflow to infrastructure
      • Deploy infrastructure
    • Adding workflows to every deploy
      • Creating a global workflow and calling another workflow
      • Creating a global workflow and adding tasks to it
      • Disabling or enabling the execution of a global workflow
  • MetalSoft Extensions

Fabric Manager

• Fabric Manager
  • Fabric Manager Overview
  • Tutorials
    • Tutorial: Switch only operation with Dell Enterprise SONiC in GNS3
      • Prerequisites
      • Download and install the Site Controller OVA
        • Configure the Site Controller
      • Import MetalSoft VM into GNS3
      • Build the topology in GNS3
      • Register the switch in MetalSoft using the CLI
      • Create a network profile
      • Adding the GNS3 PCs as un-managed servers
      • Provisioning a network using the self-service interface
      • Next steps
    • Tutorial - Dell Sonic Enterprise and Dell servers in a spine-leaf configuration
      • Cabling
      • Registering switches
      • Registering servers