Resource Group Services (Multitenancy)
This page explains how to run a containerized service (eg. SFTP, FTP, Nextcloud, Resilio, RabbitMQ or Valkey) against the network shares of a Resource Group. QuantaStor runs each service in a container, gives it the group's shares, publishes its ports only on the group's network, and moves it with the storage pool when an HA pool fails over.
| Section | Purpose |
|---|---|
| How resource group services work | Service Configs, shares, binding network and pool scope |
| Available services | The services you can run and their default ports |
| Before you start | Shares, addresses and ports to have ready |
| Step 1, Step 2, Step 3 | The workflow, start to finish |
| Adding or changing services | Changing the services on a group that already exists |
| CLI equivalents | The same workflow from the qs CLI
|
| Troubleshooting | A service that does not start or cannot be reached |
How resource group services work
A resource group set up for service container management ties together three things:
- Service Configs -- one per service, holding that service's settings (user name, password, port and so on). A group can hold one Service Config of each service type.
- Network shares -- the data the service works on. Each share in the group is bind-mounted into the service's container.
- A binding network -- a subnet in CIDR form. The service's ports are published only on the appliance addresses inside that subnet, so a client on another network cannot reach it. Two resource groups cannot bind the same subnet.
The group's Storage Pool Scope decides which addresses count and where the service keeps its state:
| Scope | Service binds to | Service state lives on |
|---|---|---|
| Local Storage Pool(s) | physical network ports in the binding subnet | the appliance's local container directory |
| HA Storage Pool | HA virtual interfaces (VIFs) in the binding subnet | the HA storage pool itself, so it moves with the pool |
Because state for an HA-scoped group lives on the pool, settings such as the SFTP host keys survive a container restart, an upgrade and an HA failover. When the pool fails over, QuantaStor stops the group's containers on the old owner, imports the pool on the new owner and starts the containers there from the same state.
- An HA-scoped group needs an HA virtual interface in its subnet. For a group scoped to an HA Storage Pool, QuantaStor publishes the service only on a virtual interface of that pool whose address falls inside the group's binding subnet. If the pool has no such VIF, the service does not start. The resource group is still created and no error appears in the web interface; the only sign is a warning in the service log that it could not determine a bind address. Create the VIF before you add the service. This applies to every service type.
Available services
We are adding new containerized services with each new release of QuantaStor but those offered at the time of this writing include Service Type of:
| Service | What it is for | Default port(s) |
|---|---|---|
| SFTP Module | SFTP access to the group's shares for one account, confined (chrooted) to those shares | 2222 |
| FTP Service | FTP access to the group's shares for one account, with optional passive mode | 20, 21 |
| Nextcloud | Web file sharing and sync; the group's shares appear as Nextcloud External Storage | 8081 (HTTP) |
| Resilio Agent | A Resilio Connect agent that synchronizes the group's shares | -- |
| RabbitMQ Message Broker | An AMQP message broker with its management console, keeping its data on a share | 5672 (AMQP), 15672 (management) |
| Valkey Data Store | A Redis-compatible key-value store that persists to a share | 6379 |
The SFTP, Nextcloud, RabbitMQ and Valkey services are defined by service definition files (qs_containerhandler_<service>.conf) in /opt/osnexus/quantastor/conf/, and their form fields come from those files. Additional definitions for MinIO, Globus Connect Server and a demonstration FTP module ship as .example files and are not offered unless enabled. To build a service of your own, see Developing Service Containers.
Before you start
- Create the network shares the service will use. For an HA-scoped group, the shares must be on that HA pool; for a local group, on a local pool. QuantaStor refuses a share that is outside the group's scope.
- Make sure the appliance has an address in the subnet clients will use -- a physical port for a local group, or an HA virtual interface on the pool for an HA group (see the note above).
- Pick a port that nothing else on the appliance uses. Do not give Nextcloud port 8080, which the QuantaStor web interface uses, and do not give SFTP port 22, which the appliance's own SSH service uses.
Step 1: Create the Service Config
You can also right-click in the Services section, or on a resource group, and choose Create Service Config....
- Name -- a name for this configuration. The default is
service-config-N. - Service Type -- the service to run, from the table above.
- Service Configuration Options -- the settings for the chosen service. This part of the dialog changes with the service type.
For the SFTP, Nextcloud, RabbitMQ and Valkey services, the options form is built from the service definition, so the fields differ from service to service. The common kinds are:
- User name and password for the account the service creates. Passwords are kept out of the service log and out of the options file the service reads. A password field never shows a default.
- Port -- a number field with a default and an allowed range.
- Check boxes for on/off settings, such as Valkey's append-only persistence.
- File uploads for keys and certificates, such as an SFTP public key or host key.
- Data share -- for Nextcloud and Valkey, which share holds the service's own data.
- An Advanced Settings group on some services. On SFTP it holds read-only access and the UID and GID that own files written through the service.
Fields the definition marks as mandatory are checked when you click OK; the form does not mark them in advance. If one is empty, the dialog reports that one or more mandatory service option fields are empty. An optional field you leave empty takes the service's default.
For the SFTP service, you must supply a password, a public key, or both. Setting read-only makes QuantaStor mount the shares read-only into the container, so clients cannot write even if the service itself would allow it. SFTP is the only service with a read-only option.
The FTP Service has fixed fields: FTP Username, FTP Password and Repeat Password. Tick Use FTP Passive Mode to let clients open passive data connections; you then have to fill in the Passive Port Range (any range within 1-65535) and the Passive IP Address to advertise to clients. Passive mode is off by default.
The Resilio Agent takes an Agent Name and a Sync File, both required.
Click OK. The Service Config appears in the Services section; it does nothing until you add it to a resource group.
Step 2: Create the resource group
The Create Resource Group page covers every tab of this dialog. For a service group:
- On the General tab, enter a Name and, optionally, a Description and Organization. Under Select Resource Group Use Case, choose Service Container Management. This enables the Service Configs tab.
- On the Service Configs tab, under Binding Network Address Setting, choose the Subnet w/CIDR the service listens on. The list shows the subnets on the appliance's network ports, minus any already bound to another resource group.
- Under Storage Pool Scope, choose Local Storage Pool(s) or HA Storage Pool. For an HA scope, select the pool in the Storage Pool list.
- Select the Service Config you created in Step 1 in the grid.
- Click OK.
If the appliance has no subnet that is not already bound to a resource group, the dialog reports that there are no available subnets. Give a network port an address on a new subnet, then try again.
To add more binding subnets later, select the group and use Add Network Association on the toolbar.
Move the shares the service should see into Select Network Shares for Resource Group Assignment and click OK. See Add Remove Resources Group Network Shares.
Each share is bind-mounted into the container. Where it lands depends on the service: SFTP users see each share as a folder in their home directory, and Nextcloud shows them as External Storage.
Adding or changing services on an existing group
Select the resource group, then select the Service Configs it should have. The selection replaces the group's list, so a config you clear is removed. A group can hold only one Service Config of each service type; selecting two of the same type is refused.
Removing a Service Config that is in use requires Force, which stops the service. See Add/Add Remove Resources Group Service Configs.
To delete a Service Config, use Delete Config in the Services toolbar group; see Service Config Delete.
CLI equivalents
List the installed service definitions and their tags with qs service-def-list. Create a Service Config with qs service-config-create, passing the definition tag and the options as a comma-separated key=value list. For example, an FTP config:
qs service-config-create --name=ftp-config1 --service-definition-tag=vsftp --service-config-options-list=ftp_user=ftpuser1,ftp_pass=aAbBcCdDeEfF
Create a service group with qs resource-group-create, giving the binding subnet with --network-list and the scope with --scope-type (local or HA) and --scope (the pool). Add shares and Service Configs with qs resource-group-resource-add, using the share and service_config resource types:
qs resource-group-resource-add --resource-group=rg-sftp --resource-list=share1:share,sftp-config1:service_config
Troubleshooting
- The service does not start in an HA-scoped group. Check that the HA pool has a virtual interface with an address in the group's binding subnet, on the node that currently owns the pool. Without one, QuantaStor has no address to publish the service on.
- Clients cannot connect. Connect to an appliance address inside the group's binding subnet -- for an HA group, the VIF address. The service is not published on other addresses. Check the port too: the services use their own defaults (for example 2222 for SFTP), not the protocol's usual port.
- A share is refused when added. The share is on a pool outside the group's scope. Move the share, or create a group scoped to the share's pool.
Related pages
- Create Resource Group
- Modify Resource Group
- Service Config Create
- Service Config Delete
- Add/Add Remove Resources Group Service Configs
- Add Remove Resources Group Network Shares
- High-availability VIF Management
- Network Shares
- Developing Service Containers
Verified against QuantaStor 6.9.0.