Mount Management
You can mount SMB/NFS shares, S3 buckets, and external devices such as USB flash drives on your Atlas system. There are two types of mounts: persistent and non-persistent. If you create a non-persistent mount, it will not be mounted after a system reboot. Please create a persistent mount if you would like the mount to persist after a reboot.
Basic Operations
You can get a list all mount options or get specific filesystem types.
List Mount Options
Get a list of all mount options.
Request Object
+ URL
/api/v2/mount/options
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The response object has filesystem types including generic, cifs, nfs, etc. Each filesystem type is an object whose keys are mount options and values are descriptions.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"generic": {
"async": "All I/O to the filesystem should be done asynchronously.",
"atime": "Do not use the noatime feature, so the inode access time is controlled by kernel defaults.",
...
},
"cifs": {
"username=": "Specifies the username to connect as. If this is not given, then the environment variable USER is used.",
"password=": "Specifies the CIFS password. If this option is not given then the environment variable PASSWD is used.",
"credentials=": "Specifies a file that contains a username and/or password and optionally the name of the workgroup.",
...
},
"nfs": {
"nfsvers=": "The NFS protocol version number used to contact the server's NFS service. If the server does not support the requested version, the mount request fails. If this option is not specified, the client negotiates a suitable version with the server, trying version 4 first, version 3 second, and version 2 last.",
"soft": "Determines the recovery behavior of the NFS client after an NFS request times out. If the soft option is specified, then the NFS client fails an NFS request after retrans retransmissions have been sent, causing the NFS client to return an error to the calling application.",
...
},
"ext4": {
"journal_dev=": "When the external journal device's major/minor numbers have changed, this option allows the user to specify the new journal location. The journal device is identified either through its new major/minor numbers encoded in devnum, or via a path to the device.",
"journal_path=": "When the external journal device's major/minor numbers have changed, this option allows the user to specify the new journal location. The journal device is identified either through its new major/minor numbers encoded in devnum, or via a path to the device.",
...
},
"fuse": {
"default_permissions": "By default FUSE doesn't check file access permissions, the filesystem is free to implement it's access policy or leave it to the underlying file access mechanism (e.g. in case of network filesystems). This option enables permission checking, restricting access based on file mode. This is option is usually useful together with the allow_other mount option.",
...
},
"goofys": {
"--cache=": "Directory to use for data cache. Requires catfs and `-o allow_other'. Can also pass in other catfs options (ex: --cache '--free:10%:$HOME/cache') (default: off)",
"--dir-mode=": "Permission bits for directories. (default: 0755) (default: 493)",
...
}
}
Find Specific Mount Options
List the mount options of a specific filesystem type (e.g. generic, cifs, nfs, goofys, ext4, etc.)
Expected Mount Types
There are 6 filesystem types we have static configurations for. They are listed below. If a filesystem type that is not included in the list is passed to this route, all of the options for every type will be returned.
-
generic: Intended to be a "catch-all" for filesystem types not included here. It is not an actual filesystem type recognized by linux.
-
cifs: The Common Internet File System. It is a form of SMB.
-
nfs: The network filesystem type. It is commonly used to access files over the network.
-
ext2: The the second iteration of the extended filesystem.
-
ext3: The third iteration of extended file systems. First to include journaling functionality.
-
ext4: The fourth iteration of extended file systems. Intended to improve performance over ext3
-
fuse: Stands for "Filesystem in Userspace". Interface for userspace programs to export a virtual filesystem to the linux kernel.
-
goofys: Allows you to mount an S3 bucket as a "filey" system. Focuses on performance first and POSIX second.
Request Object
+ URL
/api/v2/mount/options/$type
+ Method
GET
+ Parameters
type (string, required, URL param) - the filesystem type that you want to get a list of mount options of.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
You should get a list of mount options for the filesystem type that you requested.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"--cache=": "Directory to use for data cache. Requires catfs and `-o allow_other'. Can also pass in other catfs options (ex: --cache '--free:10%:$HOME/cache') (default: off)",
"--dir-mode=": "Permission bits for directories. (default: 0755) (default: 493)",
"--file-mode=": "Permission bits for files. (default: 0644) (default: 420)",
...
}
Core Mount Functionality
You can list, find, create, and unmount persistent and non-persistent mounts via the API.
List Mounts
Send this request to get a list of mounts that are currently mounted on your system.
Request Object
+ URL
/api/v2/mount
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The response object has one property, mounts, which is an array of mount objects.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"mounts": [
{
"source": "p01/f01",
"mountpoint": "/p01/f01",
"type": "zfs",
"options": {
"rw": true,
"mand": true,
"noatime": true,
"xattr": true,
"posixacl": true
},
"fs_freq": 0,
"fs_passno": 0,
"persistent": false,
"mounted": true
},
{
"source": "#/dev/sde1",
"mountpoint": "/home/open/USB",
"type": "fuseblk",
"options": {
"rw": true,
"nosuid": true,
"nodev": true,
"relatime": true,
"user_id": "0",
"group_id": "0",
"default_permissions": true,
"allow_other": true,
"blksize": "4096"
},
"fs_freq": 0,
"fs_passno": 0,
"persistent": true,
"mounted": false
}
]
}
Find Mounts
Send this request to find a specific mount on your system. You can pass "persistent" and/or "mountpoint" in the request body in order to find the mounts you are looking for. If the "mountpoint" is not included in the request, all mounts will be returned.
Request Object
+ URL
/api/v2/mount/find
+ Method
POST
+ Parameters
persistent (boolean, optional, Body) - A boolean value to filter mounts by its "persistent" property
mountpoint (string, optional, Body) - The mountpoint of a mount that you want to find
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"persistent": true
}
Response Object
The response object has one property, mounts, which is an array of mount objects.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"mounts": [
{
"source": "/dev/zvol/rpool/swap",
"mountpoint": "none",
"type": "swap",
"options": {
"defaults": true
},
"fs_freq": 0,
"fs_passno": 0,
"persistent": true,
"mounted": false
},
{
"source": "/dev/sde1",
"mountpoint": "/home/open/USB",
"type": "fuseblk",
"options": {
"rw": true,
"nosuid": true,
"nodev": true,
"relatime": true,
"user_id": "0",
"group_id": "0",
"default_permissions": true,
"allow_other": true,
"blksize": "4096"
},
"fs_freq": 0,
"fs_passno": 0,
"persistent": true,
"mounted": false
}
]
}
Create Mount
Use this request to create a mount. This route can create both persistent and non-persistent mounts.
If "persistent" parameter is not given in the request body, it will create a non-persistent mount by default.
If "mountpoint" given is an existing directory, it must not currently be a mountpoint and it must be empty. If it is not an existing directory, it will be created under the system’s /mnt directory.
Request Object
+ URL
/api/v2/mount/create
+ Method
POST
+ Parameters
source (string, required, Body) - The name of a block device, an IP address appended by a share name, or S3 bucket name. Its format depends on the filesystem type you want to mount.
mountpoint (string, required, Body) - The absolute path of a directory that you want to create a mount.
options (object, required/optional, Body) - The mount options as an object. This parameter is required if the type parameter is either cifs, s3, or goofys.
options.type (string, optional, Body) - The filesystem type. (e.g. cifs, nfs, s3, goofys, etc)
options.username (string, optional, Body) - For SMB mounts only. Use this parameter to mount using a specific user
options.password (string, optional, Body) - For SMB mounts only. This parameter is required when the username is also specified.
options.credentials (string, optional, Body) - For SMB mounts only. This parameter is required when mounting SMB and the Username/Password is not specified. It should be the location of the credentials file for SMB to use for authentication
persistent (boolean, optional, Body) - true if you want to make this mount persistent. Default to false.
mounted (boolean, optional, Body) - false if you do not want to actually mount it when sending this request, but perhaps want to just make this mount persistent. Default to true.
raw (string, optional, Body) - The raw fstab string to be used for the fstab entry. If this is included, it will override any options passed into the options object.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"source": "/dev/sde1",
"mountpoint": "/mnt/USB"
}
Unmount Mount
Unmount file systems that are currently mounted.
Request Object
+ URL
/api/v2/mount/unmount
+ Method
POST
+ Parameters
mountpoint (string, required, Body) - The absolute path of a directory that you want to unmount.
+ options (array, optional, Body) - The unmount options as an array of strings.
destroyMountpoint (boolean, optional, Body) - If true, the mountpoint directory will be removed after unmounting the filesystem. Default to false.
type (string, required, Body) - The mount type (e.g. fuse.s3backer)
source (string, required, Body) - The mount source
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"mountpoint": "/mnt/USB",
destroyMountpoint: true,
type: "fuse.s3backer",
source: "https://somefakebucket12345.s3.amazonaws.com/"
}
Persistent Mount via fstab Manipulation
Creating a persistent mount will keep the filesystem mounted after a reboot. It is the duty of the system administrator to properly create and maintain the /etc/fstab file which determines overall file system structure at boot time. Filesystem mounts in the fstab file which fail, and do not fail gracefully, will cause the system to reboot into emergency mode.
List Persistent Mount
List persistent mounts.
Request Object
+ URL
/api/v2/mount/persistent
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
You should get a response object with two properties: mounts and raw. mounts is an array of persistent mounts, and raw is the contents of the /etc/fstab file.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"mounts": [
{
"source": "/dev/zvol/rpool/swap",
"mountpoint": "none",
"type": "swap",
"options": {
"defaults": true
},
"fs_freq": 0,
"fs_passno": 0
},
{
"source": "#/dev/sde1",
"mountpoint": "/home/open/USB",
"type": "fuseblk",
"options": {
"rw": true,
"nosuid": true,
"nodev": true,
"relatime": true,
"user_id": "0",
"group_id": "0",
"default_permissions": true,
"allow_other": true,
"blksize": "4096"
},
"fs_freq": 0,
"fs_passno": 0
}
],
"raw": "# /etc/fstab: static file system information.\n#\n# Use 'blkid' to print the universally unique identifier for a\n# device; this may be used with UUID= as a more robust way to name devices\n# that works even if disks are added and removed. See fstab(5).\n#\n# <file system> <mount point> <type> <options> <dump> <pass>\n/dev/zvol/rpool/swap none swap defaults 0 0\n/dev/sde1 /home/open/USB fuseblk rw,nosuid,nodev,relatime,user_id=0,group_id=0,default_permissions,allow_other,blksize=4096 0 0\n"
}
Create Persistent Mount
Using this API route, you will create an entry in /etc/fstab. Adding an entry in the /etc/fstab file does not mean it is mounted. /etc/fstab file will be read when your Atlas system boots up, and all the entries(filesystems) in the fstab file will be mounted. Therefore, after sending a request with /api/v2/mount/persistent/create route, you still need to run either /api/v2/mount/create or /api/v2/mount/persistent/mount_all route in order to actually mount the filesystem.
Request Object
+ URL
/api/v2/mount/persistent/create
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameter
source (string, required, Body) - The name of a block device, an IP address appended by a share name, or S3 bucket name. Its format depends on the filesystem type you want to mount.
mountpoint (string, required, Body) - The absolute path of a directory that you want to create a mount.
type (string, required, Body) - The filesystem type. (e.g. cifs, nfs, s3, goofys, etc)
options (object, optional, Body) - The mount options as an object. This parameter is required if the type parameter is either cifs, s3, or goofys.
raw (string, optional, Body) - If you want to edit the contents of /etc/fstab file, please pass the contents in raw string.
+ Body
{
"source": "/dev/sde1",
"mountpoint": "/mnt/USB",
"type": "fuse"
}
Response Object
You should get a success message.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body "Successfully created new fstab entry.\ndev/sde1 /home/open/USB fuseblk rw,nosuid,nodev,relatime,user_id=0,group_id=0,default_permissions,allow_other,blksize=4096 0 0"
Delete Persistent Mount
Deleting a persistent mount is equivalent to removing an entry from the /etc/fstab file which will prevent the filesystem from being mounted on system reboot. This route does NOT unmount the filesystem. To unmount the filesystem, please use the /api/v2/mount/unmount route.
Update Persistent Mount
Update the /etc/fstab file. Currently we only provide updating the file with a raw string. Please use /api/v2/mounts/persistent route to get the raw contents, edit it, then use this route to update the file.
Request Object
+ URL
/api/v2/mount/persistent/update
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameter
raw (string, required, Body) - If you want to update the contents of /etc/fstab file, please pass the contents in raw string.
+ Body
{
"raw": "# /etc/fstab: static file system information.\n#\n# Use 'blkid' to print the universally unique identifier for a\n# device; this may be used with UUID= as a more robust way to name devices\n# that works even if disks are added and removed. See fstab(5).\n#\n# <file system> <mount point> <type> <options> <dump> <pass>\n/dev/zvol/rpool/swap none swap defaults 0 0\n#/usr/bin/goofys#/mediaingest2934 /home/open/testing_mounting fuse _netdev,allow_other,--file-mode=0666,--dir-mode=0777\n#/usr/bin/goofys#/openwasabi /home/open/wasabi fuse _netdev,allow_other,--file-mode=0666,--dir-mode=0777,--endpoint=https://s3.us-west-1.wasabisys.com,--profile=wasabi \n#/dev/sde1 /home/open/USB fuseblk rw,nosuid,nodev,relatime,user_id=0,group_id=0,default_permissions,allow_other,blksize=4096 0 0\n"
}
Profiles
To mount S3 buckets, Atlas system should know the buckets' AWS credentials: AWS Access Key ID and AWS Secret Access Key. You can list, create, and delete credentials using Profiles API routes.
List Profiles
List all profiles in your system.
Request Object
+ URL
/api/v2/mount/profile
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
You should get a success message.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"john": {
"aws_access_key_id": "A1B2C3D4E5F6G7",
"aws_secret_access_key": "A2jDj2jidfjW9Sfd$j90d"
},
"sam": {
"aws_access_key_id": "A1B2C3D4E5F6G7H8I9J0",
"aws_secret_access_key": "ji6aS2s0F3fo3SiDwjFi5of"
}
}
Create Profile
Create an AWS profile for your S3 buckets.
Request Object
+ URL
/api/v2/mount/profile/create
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameter
name (string, required, Body) - A friendly name for S3 bucket credentials
config (object, required, Body) - An object with two properties: aws_access_key_id and aws_secret_access_key. Values of the properties should be in string.
+ Body
{
"name": "michael",
"config": {
"aws_access_key_id": "A1B2C3D4E5F6G7H8",
"aws_secret_access_key": "B2jDj2$jIdfj9Sfd$jdd21Kh"
}
}
Delete Profile
Delete an AWS profile stored on your Atlas system.