File Share Services - SMB (aka "CIFS")

Apcera provides the SMB Service Gateway for accessing external file servers that support the SMB protocol.

Using SMB services

Users with data on existing external file servers can set up an SMB service to allow jobs running on the Apcera Platform to mount those file systems and access files stored on their file servers. The service can even be set up as read-only, so that jobs can read but not alter or delete data stored on external file servers.

SMB user credentials are added once, when a provider is registered or a service is created, without sharing those credentials with everyone who needs to access the data. Which jobs can connect to an SMB service is controlled within the Apcera Platform via policy.

An SMB service provides:

  • Persistent file system with customizable mount points.
  • The ability to connect to an external SMB file server using a user name and password.
  • The ability to create, update, modify, and delete files using a specific user and group name.
  • The ability to mount an external SMB share as read-write or read-only.
  • Good performance for apps that do not have IO heavy requirements.

SMB Services and SMB Providers

  • SMB Providers are producers of SMB Services from a registered SMB URL. Provider backed services are created on-demand from the provider. Each service is a unique location to store data.
  • SMB Services may also be created directly (provider-less) from a URL to access existing data.
  • SMB Services may not specify a Provider and URL during creation.
  • SMB Providers and Services are managed by the SMB Service Gateway.


SMB and CIFS are network storage protocols used to mount remote file systems over a network.

CIFS is not the network storage protocol currently used by Microsoft Windows. The protocol used to share files over a LAN by the majority of Windows-based personal computers is called SMB.

In the mid-1980s IBM invented a protocol called SMB to share files over a LAN. In the 1990s Microsoft took the SMB protocol, merged it with LAN Manager, and released is as the network storage mechanism in Windows for Workgroups.

In 1995 SMB was rebranded as CIFS, the "Common Internet File System", when Microsoft released Windows95.

In 2006 Microsoft wrote an entirely new version of the server message block protocol called SMB 2.0 and released it as part of Windows Vista. The resulting protocol is completely different than SMB 1.0 and CIFS.

To further confuse matters, the Linux subsystem used to access SMB 2.x file servers from Linux system is called mount.cifs, and is supported by When support for SMB 2.x was added the name CIFS remained in both the documentation and the name of the commands used to access the mounts.

When people or documents refer to CIFS file servers they are almost always referring to servers that support SMB 2.0 and later, not CIFS.

Accessing existing data on an external SMB server

To access data on an existing SMB server an Apcera Platform administrator will need:

  • The hostname or IP address of the server.
  • The "share name" of the SMB share with optional sub-path.
  • If the share requires authentication, a domain, username, and password are required to access the volume.

Create a SMB Service from a URL

Use the apc command to create an SMB Service:

apc service create <service name> --type smb \
	--description 'SMB External Dataset' \
	-- --url "smb://[[[authdomain;]user:password@]host[:port][/share[/path][/path2]]]"

The parameters specified after -- are called extended parameters. The extended parameter --url tells the Apcera Platform the location of an existing SMB location. Any job bound to this Service will have access to the same data. The URL used to crete a SMB Service includes the username, password, and domain to use when connecting to the SMB file server. Omitting all authentication options results in guest access.

For example, to create a SMB Service named datafiles for the domain WORKGROUP, user name roger, password dodger, hostname, where the SMB share name is myshare and desired directory is flatfiles, and a description of Project B Files you would create a service using this command:

apc service create datafiles --type smb \
	--description 'Project B Files' \
	-- --url "smb://WORKGROUP;"

Data on an SMB server which should not be modified or deleted by Jobs may be protected by creating the SMB Service with the "read-only" mount option. To create a read-only SMB Service, add the ro parameter to the SMB URL: smb://[[[authdomain;]user:password@]host[:port][/share[/path][/path2]]]?ro

Bind a SMB service to a job

Use the apc command to bind the job myjob to service datafiles:

apc service bind datafiles --job myjob

You use the extended parameter mountpath to specify the Job's mount location of the SMB Service. By default the path /smb/[share] is used. To specify a an extended parameter you append -- to the command string followed by the extended parameter name and value. For example, the following binds a job to the datafiles SMB service at the mountpath of /data/files:

apc service bind datafiles --job myjob -- --mountpath /data/files

Many jobs may be bound to the same service, effectively sharing the same SMB Location between all jobs. A job may be bound to many services, effectively granting the job access to many SMB Locations. Jobs bound to multiple services residing on shares with the same name are strongly encouraged to select a unique path for each binding with the mountpath parameter; otherwise the job will fail to start with the error device or resource busy.

Pro Tip: It is possible to create a Service and Bind it to an existing job in one step by adding the -j option to 'apc service bind'. However, binding extended parameters such as mountpath may not be supplied.

Example: Create a Capsule and Bind to an SMB Service

A share can be accessed from inside a container by creating a capsule and binding a service to it:

apc capsule create smb-test-capsule --image linux
apc service bind <service name> -j smb-test-capsule
apc capsule connect smb-test-capsule

Once connected to the capsule, mount -t cifs shows the SMB mount, df -h lists the free space. ls /smb/[share] lists the files located in the SMB Service.

Using an SMB server to provide multi-tenant "namespaced" storage for Apcera Platform jobs

In addition to accessing existing data on an SMB file server, an SMB location may provide persistent, multi-tenant "namespaced" storage to Apcera Platform jobs. With namespaced storage, each service created from a provider will create a new, unique subdirectory within the registered provider location. Jobs bound to the same service share storage. Multiple services may use the same provider, each one isolated from the others.

Create a namespaced provider

Use the apc command to create a provider:

apc provider register <provider name> --type smb \
	--url "smb://[[[authdomain;]user:password@]host[:port][/share[/path][/path2]]]" \
	--description 'SMB Multi-Tenant Provider'

Apcera creates a namespaced provider. Any service created from this provider will create a unique, isolated subdirectory within the provider.

For example, to create a namespaced provider named container_data for the domain WORKGROUP, user name admin, password zippy, hostname, where the exported directory on the SMB server is /srv/containerdata, you would create a provider using this command:

apc provider register container_data --type smb \
	--url "smb://WORKGROUP;" \
	--description 'Storage for containers'

Create a namespaced service

Use the apc command to create a service:

apc service create <service name> --provider <provider name> --description 'SMB Tenant Service'

Bind the namespaced service to a job

Just to show that the share can be mounted inside a container, create a capsule and bind the service to it:

apc capsule create smb-test-ns --image linux
apc service bind <service name> -j smb-test-ns
apc capsule connect smb-test-ns

Once connected to the capsule,mount -t cifs shows the SMB mount, df -h lists the free space. ls /smb/[share] will list an empty directory. Files stored in this directory will persist even when the job is restarted. Different jobs bound to the same service will share the same files. Jobs bound to a different service will not see these files.

Use the extended parameter mountpath to specify the directory to mount the SMB service. By default mountpath is /smb/[share].

Creating a provider from an SMB share which does not require authentication

An SMB share may allow for unauthenticated access. To create a provider that connects to a public share:

apc provider register <provider name> --type smb \
	--url "smb://host[:port][/share[/path][/path2]]]" \
	--description 'SMB Public Provider'

Since no user name or password are provided the system will attempt to mount the share with no security at all. As long as the share and file permissions allow for "public" ("Guest Account" + "Everyone" group) access.

Additional URL options

URL options apply equally to Services created via provider or directly from a URL. The only expectation being that "Read-Only", ro, is not a valid mount option for when registering a provider.


Appending ro to the SMB URL will ensure the SMB client mounts the remote storage as "read only". This has no effect on the permissions granted to the account used to connect to storage on the SMB server.

Version options

By default the mounter will use SMB version 2.0. To set a specific version append the parameter vers=<version>. Valid versions are:

  • 1.0 – Legacy Support
  • 2.0 – Windows Vista/Server 2008 and newer. More Info
  • 2.1 – Windows 7 and Server 2008 R2 More Info
  • 3.0 – Windows 8 and Windows Server 2012 More Info
  • 3.02 – Windows 8.1 and Windows Server 2012 R2 More Info

Compatiblity is determined by the client and the server. Consult your storage provider when selecting a version. Apcera deploys cifs utils version 6.0 and kernel 3.13

Authentication options

By default the mounter will use the SMB security mode ntlmssp. If you need to set it to a specific security mode use the URL parameter sec=<security mode>. Valid security modes are:

  • none – Attempt to connection as a null user (no name).
  • ntlm – Use NTLM password hashing.
  • ntlmi – Use NTLM password hashing and force packet signing.
  • ntlmv2 – Use NTLMv2 password hashing.
  • ntlmv2i – Use NTLMv2 password hashing and force packet signing.
  • ntlmssp – Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message. (default)
  • ntlmsspi – Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message, and force packet signing.

kerb5 (Kerberos version 5 authentication) and krb5i (Kerberos authentication with forcibly enabled packet signing) are not supported by the Apcera Platform at this time.

Specifying a non-standard port

The SMB server port defaults to 445. If you need to set it to some other number, use host:port in the URL.


The SMB uid and gid mount options default to the UID and GID of the root user of the container. If you wish to make the files appear to be owned by a specific user ID and/or group ID within the container, use the uid and gid options in the URL.

UIDs and GIDs specified in the URL only have meaning within the container. On SMB server, all file access appears to be owned by the user specified by "user name".

Putting it all together

For example, to create a namespaced provider named smb_special for the domain WORKGROUP, user name amanda, password vGj8Hp1, hostname, exported directory /srv/mydata, server is running SMB version 3.02, NTLMv2 password hashing, port 40145, and you want to read and write files as user ID 1000, group ID 1001, you would create a provider using this command:

apc provider register smb_special --type smb \
	--url "smb://WORKGROUP;" \
	--description 'Win2012 Server with specific version and authentication reqirements'

Using Encrypted SMB services

When you create a namespaced SMB service you have the option of enabling EncFS encryption on the service. Any job bound to an encrypted SMB service has its data (file contents and names) transparently encrypted before being written to disk, and similarly decrypted during data read operations. This is often referred to a "encryption at rest". It prevents access to the data on the encrypted volume if, for example, the host virtual machine were decommissioned and its drive space re-assigned to another app, or if a hard disk were removed from a cluster and installed in a new environment. And because data can only be decrypted within the running job instance (container) on the Instance Manager, it also protects against someone reading your data by sniffing network packets.

This feature does not protect against application-level security failures, such as a SQL injection attack.

Note: EncFS encryption is not supported non-namespaced SMB services.

During service creation a secret key is generated that is used to perform the encryption, and is stored securely in the platform's secret storage (FIXME). When a job that's bound to an encrypted SMB service is started the secret key is retrieved from secret storage and used to start EncFS.

To make an encrypted SMB service you pass --encrypt true as an extended parameter when creating the service, for example:

apc service create encrypted-file-service \
--provider /apcera/providers::smb -- --encrypt true

You can also pass the --encrypt true extended parameter when registering a non-shared SMB provider. Any SMB service you then create from that provider inherits the data encryption setting. For example, the following creates an SMB provider with the --encrypt true extended parameter:

apc provider register encrypted_smb_provider --type smb \
	--url "smb://" \
	--description 'Encrypted SMB storage provider' \
	-- --encrypt true

Any service you create from that provider You can then create an encrypted SMB service from that provider:

apc service create encrypted-file-service- \
--provider /providers::encrypted_nfs_provider

Note: To be able to see the encrypt field of services in clusters running version < 3.2.0, policy should be updated to allow exporting it:

on gateway::/apcera/service-gateways::smb {
  { permit use }
  { serviceParam encrypt }

Note: Data on an encrypted SMB volume can only be decrypted by a job that is bound to the corresponding SMB service; you cannot use another tool to export and decrypt the data for use in another environment.

Note: File-locking does not work on remote encrypted volumes. If your application requires file-locking in order to work, you cannot use encryption.

You can automate the enforcement of application data encryption using policy. See policy for data at rest encryption.