Filesystems
There are some generic items that we make available on all types of filesystems, they’re gathered here.
Filesystem Exploration
Say you have an external filesystem available, you want to mount it and see what’s on it, here’s some routes to help with that.
Available Filesystems
Which filesystems are available to be used on your OpenDrives System?
Request Object
+ URL
/api/v2/fs/available_fs
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
You should get back an array of Available Filesystems.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
[
{
"device_associated": false,
"name": "sysfs"
},
{
"device_associated": false,
"name": "rootfs"
},
{
"device_associated": true,
"name": "squashfs"
},
{
"device_associated": false,
"name": "overlay"
}
]
Create a Filesystem
Let’s say that you have a loopback device that you’ve created and initialized at /loopbackfile.img. Now let’s create a filesystem on top of that loopback device.
Request Object
+ URL
/api/v2/fs/make_filesystem
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
device (string, required, body) - The device to utilize for creating your filesystem.
type (string, required, body) - The type of filesystem to create.
options (array, optional, body) - The options to use when creating the filesystem.
+ Body
{
"device": "/loopbackfile.img",
"type": "ext4"
}
Response Object
You should get back the raw output of creating that fs.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body "Discarding device blocks: 4096/256000\b\b\b\b\b\b\b\b\b\b\b\b\b \b\b\b\b\b\b\b\b\b\b\b\b\bdone \nCreating filesystem with 256000 4k blocks and 64000 inodes\nFilesystem UUID: 822c7432-7143-4139-931d-4dea7a54d739\nSuperblock backups stored on blocks: \n\t32768, 98304, 163840, 229376\n\nAllocating group tables: 0/8\b\b\b \b\b\bdone \nWriting inode tables: 0/8\b\b\b \b\b\bdone \nCreating journal (4096 blocks): done\nWriting superblocks and filesystem accounting information: 0/8\b\b\b \b\b\bdone\n\n"
Make a directory
Now that your filesystem is created, you might want to mount. Start by creating a directory to mount into.
Request Object
+ URL
/api/v2/fs/make_directory
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
destination (string, required, body) - The absolute path of the directory you would like to create.
options (array, optional, body) - The options to send to DD.
+ Body
{
"destination": "/media/hyperloop"
}
Mount a Filesystems
Now that your filesystem is created and you have a place to mount it, let’s mount it.
Request Object
+ URL
/api/v2/fs/mount
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
device (string, required, body) - The device to utilize for mounting your filesystem.
mountpoint (string, required, body) - The absolute path of the mountpoint.
+ Body
{
"device": "/loopbackfile.img",
"mountpoint": "/media/hyperloop"
}
Explore a Filesystems
Since everything has been created and mounted, let’s see the brand new filesystem in action.
Request Object
+ URL
/api/v2/fs/explore
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
fs_path (string, required, body) - The absolute path of the filesystem you would like to explore.
+ Body
{
"fs_path": "/media/hyperloop/"
}
Response Object
You should get a JSON object with a lot of data about what’s in that filesystem path.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"files": [
{
"dev": 1792,
"mode": 16832,
"nlink": 2,
"uid": 0,
"gid": 0,
"rdev": 0,
"blksize": 4096,
"ino": 11,
"size": 16384,
"blocks": 32,
"atimeMs": 1596741095000,
"mtimeMs": 1596741095000,
"ctimeMs": 1596741095000,
"birthtimeMs": 1596741095000,
"atime": "2020-08-06T19:11:35.000Z",
"mtime": "2020-08-06T19:11:35.000Z",
"ctime": "2020-08-06T19:11:35.000Z",
"birthtime": "2020-08-06T19:11:35.000Z",
"file_num": 0,
"name": "lost+found",
"path": "/media/hyperloop/lost+found",
"isSymbolicLink": false,
"isBlockDevice": false,
"isDirectory": true,
"isFile": false,
"children": []
}
],
"total": 1
}
Unmount a Filesystems
Finally, Let’s unmount a filesystem.
Request Object
+ URL
/api/v2/fs/unmount
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
device (string, optional, body) - The device we should unmount.
mountpoint (string, required, body) - The full path of the mountpoint of the filesystem we should unmount.
+ Body
{
"mountpoint": "/media/hyperloop"
}
Set permissions on a Filesystems
Another common use case is to set permissions on a filesystem.
Request Object
+ URL
/api/v2/fs/set_permissions
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
path (string, required, body) - The absolute path of the directory or file whose acls should change.
acls (array, optional, body) - The acls you would like to apply. For more details, refer to https://man7.org/linux/man-pages/man1/setfacl.1.html[setfacl manual page]
defaults (boolean, optional, body) - Apply the default acls to the directory or filesystem.
recursive (boolean, optional, body) - Apply operations to all files and directories recursively.
test (boolean, optional, body) - Test mode. Instead of changing the ACLs of any files, the resulting ACLs are listed.
+ Body
{
"path": "/home/open/test_dir",
"acl": ["user::rwx", "group::rwx", "other::r"]
}
Hashing files
A common use case is verifying file checksums to ensure data integrity when ingesting files from an external source, to help in that aspect, we have created routes to allow the use of the 'xxhash' tool.
Generate Hashes
You can send an array of filenames into the xxhasher and get back sums for each of them. This uses options provided by xxhash’s xxhsum command.
Request Object
+ URL
/api/v2/fs/xxhash
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
filenames (array, required, body) - The names of the files you would like to hash.
options (array, optional, body) - Options to use while hashing the files.
+ Body
{
"fileNames": ["/media/hyperloop/test.txt"],
"options": ["-H0"]
}
Verify Hashes
Sometimes external programs will generate their own file of hashes to verify against. To run xxhash verification, just call this route with said file. Please note: You want to specify the filepath absolutely when generating the verification file. This file was generated with this command xxhsum /media/hyperloop/*.txt > ./h.sums (Note the absolute filepath given for the hyperloop mount point)
Request Object
+ URL
/api/v2/fs/xxhash_verify
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Parameters
checksumFile (string, required, body) - The absolute path of a file containing a list of checksum hash and file name pairings in xxhash format
options (array, optional, body) - The options to use when checksumming
+ Body
{
"checksumFile": "/media/hyperloop/h.sums"
}
Response Object
You will get back JSON output with the results of verifying the hash file.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"results": [
{
"fileName": "/media/hyperloop/test.txt",
"result": "OK"
}
],
"verified": true
}