SMB
OpenDrives systems make use of Samba, a re-implementation of the SMB networking protocol. SMB, or Server Message Block, provides shared access to the filesystems on your OpenDrives system, allowing users to view, store, update, or share files on a remote system as if it were a local system.
Basic Operations
SMB shares may be created, read, updated, and destroyed via the API. A filesystem may have multiple SMB shares, each with their own set of parameters.
List SMB Shares
Send this request to get back a list of SMB shares on the OpenDrives system.
Request Object
+ URL
/api/v2/smb
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
Sending this should get you back a valid response, if you’ve sent correct credentials.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"fs_001_share_1": {
"raw": "[fs_001_share_1]\n\tpath = /P01/fs_001\n\tavailable = yes\n\tbrowseable = yes\n\taccess based share enum = yes\n\tea support = yes\n\tfruit:aapl = yes\n\tfruit:copyfile = yes\n\tfruit:delete_empty_adfiles = yes\n\tfruit:encoding = private\n\taio read size = 1\n\taio write size = 1\n\tcase sensitive = yes\n\tcreate mask = 0666\n\tdelete veto files = yes\n\tdirectory mask = 0777\n\tfruit:locking = none\n\tfruit:metadata = netatalk\n\tfruit:model = MacSamba\n\tfruit:nfs_aces = yes\n\tfruit:posix_rename = yes\n\tfruit:resource = file\n\tfruit:veto_appledouble = no\n\tfruit:wipe_intentionally_left_blank_rfork = yes\n\tfruit:zero_file_id = yes\n\tmangled names = no\n\tread only = no\n\treaddir_attr:aapl_finder_info = yes\n\treaddir_attr:aapl_max_access = yes\n\treaddir_attr:aapl_rsize = no\n\tstrict sync = no\n\tuse sendfile = yes\n\tvfs objects = catia fruit streams_xattr acl_xattr aio_pthread",
"active": true,
"available": "yes",
"path": "/P01/fs_001"
}
}
Get Active Shares
Send this request to receive an array containing the raw output of every active SMB share on the OpenDrives system.
Request Object
+ URL
/api/v2/smb/local
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
Sending this should get you back a valid response, if you’ve sent correct credentials.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/array; charset=utf-8
+ Body
[
"[fs_001_share_1]\n\tpath = /P01/fs_001\n\tavailable = yes\n\tbrowseable = yes\n\taccess based share enum = yes\n\tea support = yes\n\tfruit:aapl = yes\n\tfruit:copyfile = yes\n\tfruit:delete_empty_adfiles = yes\n\tfruit:encoding = private\n\taio read size = 1\n\taio write size = 1\n\tcase sensitive = yes\n\tcreate mask = 0666\n\tdelete veto files = yes\n\tdirectory mask = 0777\n\tfruit:locking = none\n\tfruit:metadata = netatalk\n\tfruit:model = MacSamba\n\tfruit:nfs_aces = yes\n\tfruit:posix_rename = yes\n\tfruit:resource = file\n\tfruit:veto_appledouble = no\n\tfruit:wipe_intentionally_left_blank_rfork = yes\n\tfruit:zero_file_id = yes\n\tmangled names = no\n\tread only = no\n\treaddir_attr:aapl_finder_info = yes\n\treaddir_attr:aapl_max_access = yes\n\treaddir_attr:aapl_rsize = no\n\tstrict sync = no\n\tuse sendfile = yes\n\tvfs objects = catia fruit streams_xattr acl_xattr aio_pthread",
"[fs_002_share_1]\n\tpath = /P01/fs_002\n\tavailable = yes\n\tbrowseable = yes"
]
Get SMB Share
Send this request to recieve the details of a specific SMB share on the OpenDrives system.
Request Object
+ URL
/api/v2/smb/$SHARE_NAME/details
+ Method
GET
+ Parameters
share name (string, required, URL param) - the name of the share you would like to view
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
Sending this should get you back a valid response, if you’ve sent correct credentials.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"name": "fs_001_share_1",
"active": true,
"available": "yes",
"raw": "[fs_001_share_1]\n\tpath = /P01/fs_001\n\tavailable = yes\n\tbrowseable = yes",
"json": {
"path": "/P01/fs_001",
"available": "yes",
"browseable": "yes"
},
"path": "/P01/fs_001"
}
Create SMB Share
Any number of SMB shares can be created for any filepath on your OpenDrives system.
Request Object
+ URL
/api/v2/smb/create
+ Method
POST
+ Parameters
name (string, required, Body) - the name you would like to give this share
parameters (object, required, Body) - an object of samba parameters to include in the share
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"name": "fs_001_share_1",
"parameters": {
"path": "/P01/fs_001",
"available": "yes",
"browseable": "yes"
}
}
Update SMB Share
SMB shares can be updated in the same fashion they are created by using this route.
Request Object
+ URL
/api/v2/smb/$SHARE_NAME/update
+ Method
POST
+ Parameters
share (string, required, URL param) - the name of the share you would like to update
parameters ([object, string], required, Body) - an object or raw string of samba parameters to include in the share
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"parameters": {
"path": "/P01/fs_001",
"available": "yes",
"browseable": "yes"
}
}
Rename SMB Share
SMB shares can be renamed by way of this route.
Request Object
+ URL
/api/v2/smb/$SHARE_NAME/rename
+ Method
POST
+ Parameters
share (string, required, URL param) - the name of the share you would like to rename
newName (string, required, Body) - the new name to be given to the share
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"newName": "fs_001_main"
}
Remove SMB Share
This route will remove a designated SMB share from your system. Be careful, as there is no confirmation required and this action is final.
Activate SMB Share
SMB shares can be made either active or inactive. This modifies the availability of the share while retaining the share’s configuration.
Deactivate SMB Share
SMB shares can be made either active or inactive. This modifies the availability of the share while retaining the share’s configuration.
Request Object
+ URL
/api/v2/smb/$SHARE_NAME/deactivate
+ Method
POST
+ Parameters
share name (string, required, URL param) - the name of the share you would like to deactivate
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"share": "fs_001_share_1",
}
Test SMB Share
This route will return the testparm output of a designated share. Testparm is a simple test program that checks an smb configuration file for internal correctness. Testparm output is useful for troubleshooting problematic shares.
Request Object
+ URL
/api/v2/smb/$SHARE_NAME/test
+ Method
GET
+ Parameters
share name (string, required, URL param) - the name of the share you would like to test
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"warnings": "Registered MSG_REQ_POOL_USAGE\nRegistered MSG_REQ_DMALLOC_MARK and LOG_CHANGED\nLoad smb config files from /etc/samba/shares.conf.d/fs_001_share_1.conf\nProcessing section \"[fs_001_share_1]\"\nLoaded services file OK.\nServer role: ROLE_STANDALONE\n\n",
"raw": "# Global parameters\n[global]\n\tidmap config * : backend = tdb\n\n\n[fs_001_share_1]\n\tpath = /P01/fs_001\n"
}
Test System SMB Configuration
This route will return the testparm output of your entire system, all shares included. Testparm is a simple test program that checks an smb configuration file for internal correctness. Testparm output is useful for troubleshooting problematic shares.
Request Object
+ URL
/api/v2/smb/test
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"warnings": "Can't find include file /etc/samba/smb-nmbd.conf.local\nUnknown parameter encountered: \"auth methods\"\nIgnoring unknown parameter \"auth methods\"\nCan't find include file /etc/samba/smb.conf.local\nRegistered MSG_REQ_POOL_USAGE\nRegistered MSG_REQ_DMALLOC_MARK and LOG_CHANGED\nLoad smb config files from /etc/samba/smb.conf\nCan't find include file /etc/samba/smb-nmbd.conf.local\nUnknown parameter encountered: \"auth methods\"\nIgnoring unknown parameter \"auth methods\"\nCan't find include file /etc/samba/smb.conf.local\nProcessing section \"[defaultsettings]\"\nWARNING: No path in service defaultsettings - making it unavailable!\nNOTE: Service defaultsettings is flagged unavailable.\nProcessing section \"[fs_001_share_1]\"\nLoaded services file OK.\nWARNING: socket options = IPTOS_LOWDELAY SO_RCVBUF=131072 TCP_NODELAY\nThis warning is printed because you set one of the\nfollowing options: SO_SNDBUF, SO_RCVBUF, SO_SNDLOWAT,\nSO_RCVLOWAT\nModern server operating systems are tuned for\nhigh network performance in the majority of situations;\nwhen you set 'socket options' you are overriding those\nsettings.\nLinux in particular has an auto-tuning mechanism for\nbuffer sizes (SO_SNDBUF, SO_RCVBUF) that will be\ndisabled if you specify a socket buffer size. This can\npotentially cripple your TCP/IP stack.\n\nGetting the 'socket options' correct can make a big\ndifference to your performance, but getting them wrong\ncan degrade it by just as much. As with any other low\nlevel setting, if you must make changes to it, make\n small changes and test the effect before making any\nlarge changes.\n\nWARNING: some services use vfs_fruit, others don't. Mounting them in conjunction on OS X clients results in undefined behaviour.\n\nServer role: ROLE_STANDALONE\n\n",
"raw": "# Global parameters\n[global]\n\tidmap config * : backend = tdb\n\n\n[fs_001_share_1]\n\tpath = /P01/fs_001\n"
}
List Recommended SMB Settings
Your OpenDrives system comes with a recommended default template as well as the ability to set settings templates for SMB shares. This route returns those templates.
Request Object
+ URL
/api/v2/smb/defaults
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"basic": {
"raw": "available = yes\nbrowseable = yes\naccess based share enum = yes\nea support = yes\nfruit:aapl = yes\nfruit:copyfile = yes\nfruit:delete_empty_adfiles = yes\nfruit:encoding = private\naio read size = 1\naio write size = 1\ncase sensitive = yes\ncreate mask = 0666\ndelete veto files = yes\ndirectory mask = 0777\nfruit:locking = none\nfruit:metadata = netatalk\nfruit:model = MacSamba\nfruit:nfs_aces = yes\nfruit:posix_rename = yes\nfruit:resource = file\nfruit:veto_appledouble = no\nfruit:wipe_intentionally_left_blank_rfork = yes\nfruit:zero_file_id = yes\nmangled names = no\nread only = no\nreaddir_attr:aapl_finder_info = yes\nreaddir_attr:aapl_max_access = yes\nreaddir_attr:aapl_rsize = no\nstrict sync = no\nuse sendfile = yes\nvfs objects = catia fruit streams_xattr acl_xattr aio_pthread",
"json": {
"available": "yes",
"browseable": "yes",
"access based share enum": "yes",
"ea support": "yes",
"fruit:aapl": "yes",
"fruit:copyfile": "yes",
"fruit:delete_empty_adfiles": "yes",
"fruit:encoding": "private",
"aio read size": "1",
"aio write size": "1",
"case sensitive": "yes",
"create mask": "0666",
"delete veto files": "yes",
"directory mask": "0777",
"fruit:locking": "none",
"fruit:metadata": "netatalk",
"fruit:model": "MacSamba",
"fruit:nfs_aces": "yes",
"fruit:posix_rename": "yes",
"fruit:resource": "file",
"fruit:veto_appledouble": "no",
"fruit:wipe_intentionally_left_blank_rfork": "yes",
"fruit:zero_file_id": "yes",
"mangled names": "no",
"read only": "no",
"readdir_attr:aapl_finder_info": "yes",
"readdir_attr:aapl_max_access": "yes",
"readdir_attr:aapl_rsize": "no",
"strict sync": "no",
"use sendfile": "yes",
"vfs objects": "catia fruit streams_xattr acl_xattr aio_pthread"
}
},
"ctdb": {
"raw": "available = yes\nbrowseable = yes\naccess based share enum = yes\nfruit:aapl = yes\nfruit:copyfile = yes\nfruit:delete_empty_adfiles = yes\nfruit:encoding = private\naio read size = 1\naio write size = 1\ncase sensitive = yes\ncreate mask = 0666\ndelete veto files = yes\ndirectory mask = 0777\nfruit:locking = none\nfruit:metadata = netatalk\nfruit:model = MacSamba\nfruit:nfs_aces = yes\nfruit:posix_rename = yes\nfruit:resource = file\nfruit:veto_appledouble = no\nfruit:wipe_intentionally_left_blank_rfork = yes\nfruit:zero_file_id = yes\nmangled names = no\nread only = no\nreaddir_attr:aapl_finder_info = yes\nreaddir_attr:aapl_max_access = yes\nreaddir_attr:aapl_rsize = no\nstrict sync = no\nuse sendfile = yes\nvfs objects = fileid catia fruit streams_xattr acl_xattr aio_pthread\nfileid:algorithm = fsname\nnt acl support = yes\nea support = yes",
"json": {
"available": "yes",
"browseable": "yes",
"access based share enum": "yes",
"fruit:aapl": "yes",
"fruit:copyfile": "yes",
"fruit:delete_empty_adfiles": "yes",
"fruit:encoding": "private",
"aio read size": "1",
"aio write size": "1",
"case sensitive": "yes",
"create mask": "0666",
"delete veto files": "yes",
"directory mask": "0777",
"fruit:locking": "none",
"fruit:metadata": "netatalk",
"fruit:model": "MacSamba",
"fruit:nfs_aces": "yes",
"fruit:posix_rename": "yes",
"fruit:resource": "file",
"fruit:veto_appledouble": "no",
"fruit:wipe_intentionally_left_blank_rfork": "yes",
"fruit:zero_file_id": "yes",
"mangled names": "no",
"read only": "no",
"readdir_attr:aapl_finder_info": "yes",
"readdir_attr:aapl_max_access": "yes",
"readdir_attr:aapl_rsize": "no",
"strict sync": "no",
"use sendfile": "yes",
"vfs objects": "fileid catia fruit streams_xattr acl_xattr aio_pthread",
"fileid:algorithm": "fsname",
"nt acl support": "yes",
"ea support": "yes"
}
}
}
Set Recommended SMB Settings
You can add an SMB recommended settings file with this route.
Reload SMB configurations
Use this route to apply changes in SMB configurations without restarting smbd.service.
Get SMB Status
Use this route to see general information about how your SMB configuration is currently being used. With this route, you can view information like the Samba version you are running, users accessing the SMB shares you have created, which files those users are accessing and metadata about those files.
Request Object
+ URL
/api/v2/smb/status
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"version": "4.9.5-Debian",
"protocols": [
{
"pid": "20254",
"name": "dschrute",
"group": "staff",
"machine": "10.0.17.22",
"machine_more": "(ipv4:10.0.17.22:55306)",
"protocol": "SMB3_11",
"encryption": "-",
"signing": "partial(AES-128-CMAC)"
}
],
"services": [
{
"service": "P02_meta",
"pid": "20254",
"machine": "10.0.17.22",
"encryption": "-",
"signing": "-",
"connected_at": "Fri Feb 4 08:35:48 AM 2022 PST"
}
],
"files": [
{
"pid": "20254",
"uid": "1001",
"deny_mode": "DENY_NONE",
"access": "0x20081",
"read_write": "RDONLY",
"op_lock": "NONE",
"share_path": "/P02/meta",
"file_path": "journal_log.txt",
"connected_at": "Fri Feb 4 08:41:51 2022"
},
{
"pid": "20254",
"uid": "1001",
"deny_mode": "DENY_NONE",
"access": "0x100081",
"read_write": "RDONLY",
"op_lock": "NONE",
"share_path": "/P02/meta",
"file_path": ".",
"connected_at": "Fri Feb 4 08:35:48 2022"
},
{
"pid": "20254",
"uid": "1001",
"deny_mode": "DENY_NONE",
"access": "0x100081",
"read_write": "RDONLY",
"op_lock": "NONE",
"share_path": "/P02/meta",
"file_path": ".",
"connected_at": "Fri Feb 4 08:41:46 2022"
}
]
}
List SMB Users
Use this route to list all Samba users. The number of Samba users on your system or domain server affects the amount of time this request returns the data. If getting the list of Samba users takes more than 30 seconds, it may return 504 Gateway Time-out error.
Canceling the API request from the client machine will not stop the process of listing the Samba users on your Atlas system. If you canceled the request and want to completely terminate the process that’s running on the Atlas system, you have to manually end the process on CLI. ps aux | grep pdbedit will return the currently running processes, and the second argument of each process row is the process ID (PID). Pass the PID to the following command to kill the process: sudo kill <PID>
Get SMB User
Use this route to get details about a specific Samba user.
Request Object
+ URL
/api/v2/smb/users/$USERNAME/details
+ Method
GET
+ Parameters
username (string, required, URL param) - the Samba username that you want more details about
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"raw": "Unix username: mscott\nNT username: \nAccount Flags: [U ]\nUser SID: S-1-5-21-4241128709-3628615702-2632530113-1003\nPrimary Group SID: S-1-5-21-4241128709-3628615702-2632530113-513\nFull Name: \nHome Directory: \\\\opendrives-323106a0\\mscott\nHomeDir Drive: \nLogon Script: \nProfile Path: \\\\opendrives-323106a0\\mscott\\profile\nDomain: OPENDRIVES-323106A0\nAccount desc: \nWorkstations: \nMunged dial: \nLogon time: 0\nLogoff time: Wed, 06 Feb 2036 07:06:39 PST\nKickoff time: Wed, 06 Feb 2036 07:06:39 PST\nPassword last set: Fri, 04 Feb 2022 08:55:58 PST\nPassword can change: Fri, 04 Feb 2022 08:55:58 PST\nPassword must change: never\nLast bad password : 0\nBad password count : 0\nLogon hours : FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF\n"
}
Verify a Samba User
You can verify if there’s a Samba user on your system or your domain server (if your system is bound to a domain) using this route.
Global Operations
List Global SMB Configuration Files
SMB has a number of files for configuring system-wide SMB settings. This route informs you of those files and the keys by which to view their contents via the Get Global SMB Configuration File route.
Request Object
+ URL
/api/v2/smb/global
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"smb": "smb.conf",
"auth": "smb-auth.conf",
"performance": "smb-performance.conf",
"printers": "smb-printers.conf",
"logs": "smb-logs.conf",
"shares": "smb-shares.conf",
"database": "smb-database.conf"
}
Get Global SMB Configuration File
SMB has a number of files for configuring system-wide SMB settings. Use this route to view the contents of those files. Provide the config key for the desired file in the URL of the request. Keys can be found via the List Global SMB Configuration Files route.
Request Object
+ URL
/api/v2/smb/global/$CONFIG_KEY/details
+ Method
GET
+ Parameters
config key (string, required, URL param) - the key of the file you would like to view
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/string; charset=utf-8 + Body "[global]\n\t# define basic global parameters here.\n\t# porpose-specific parameters specified in \n\t# include files referenced below. \n available = yes\n\tntlm auth = yes\n\tusershare path =\n ntlm auth = yes\n \n\t# nmbd options\n\tinclude = /etc/samba/smb-nmbd.conf\n\t\n\t# auth options\n\tinclude = /etc/samba/smb-auth.conf\n\n\t# performance tuning \t\n\tinclude = /etc/samba/smb-performance.conf\n\n\t# printers\n\tinclude = /etc/samba/smb-printers.conf\n\n\t# log options \n\tinclude = /etc/samba/smb-logs.conf\n\n\t# local overrides\n\tinclude = /etc/samba/smb.conf.local\n\n# shares - this is it's own subsection\ninclude = /etc/samba/smb-shares.conf\n\n"
Write Global SMB Configuration File
SMB has a number of files for configuring system-wide SMB settings. Use this route to edit the contents of those files. Provide the config key for the desired file in the URL of the request. Keys can be found via the List Global SMB Configuration Files route.
Request Object
+ URL
/api/v2/smb/global/$CONFIG_KEY/write
+ Method
POST
+ Parameters
config key (string, required, URL param) - the key of the file you would like to write
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"file": "auth",
"contents": "This will become the new contents of the global config file. Please be very careful and only edit these if you really know what you are doing"
}
Authentication Operations
Operations in this section are to check current SMB authentication type (whether it’s local or Active Directory), get local/AD authentication information, enable local/AD authentication, join/leave a domain, and getting AD status.
|
Below terms are used interchangeably in this context:
|
Get Authentication Type
Send this request to check if your system’s current authentication type is local or Active Directory.
Get Global Authentication Configuration File
Send this request to retrieve the Samba global authentication configuration stored in /etc/samba/smb-auth.conf.
Request Object
+ URL
/api/v2/smb/auth/global
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The contents of the Samba global authentication configuration file in both raw text and json formats.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"raw": "include = /etc/samba/smbauth.conf.d/ad_provider.conf",
"json": {
"ad_provider": "include = /etc/samba/smbauth.conf.d/ad_provider.conf"
}
}
Set Global Authentication Configuration File
Write to the Samba global authentication configuration file stored at /etc/samba/smb-auth.conf
Request Object
+ URL
/api/v2/smb/auth/global
+ Method
POST
+ Parameters
conf ([string, object], required, Body) - Can be either a string containing the raw text or an object representing the values that should be included into the global conf file.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"conf": {
"include": "/etc/samba/smbauth.conf.d/ad_provider.conf"
}
}
List Individual Authentication Configuration Files
Send this request to list all of the individual authentication configuration files on your system.
Request Object
+ URL
/api/v2/smb/auth/individual
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The contents of each file stored in /etc/samba/smbauth.conf.d as raw text and json objects.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"ad_provider": {
"raw": "workgroup = openlab\nrealm = openlab.com\nname resolve order = host wins bcast\nclient signing = if_required\nkerberos method = secrets and keytab\nsecurity = domain\ntemplate shell = /bin/false\ntemplate homedir = /home/%U\nidmap config openlab:backend = ad\nidmap config openlab:schema_mode = rfc2307\nidmap config openlab:range = 10000-999999\n",
"json": {
"workgroup": "openlab",
"realm": "openlab.com",
"name resolve order": "host wins bcast",
"client signing": "if_required",
"kerberos method": "secrets and keytab",
"security": "domain",
"template shell": "/bin/false",
"template homedir": "/home/%U",
"idmap config openlab:backend": "ad",
"idmap config openlab:schema_mode": "rfc2307",
"idmap config openlab:range": "10000-999999"
}
},
"local": {
"raw": "auth methods = sam\npassdb backend = tdbsam\nguest account = nobody\nmap to guest = Bad User\nusername map cache time = 60\n",
"json": {
"auth methods": "sam",
"passdb backend": "tdbsam",
"guest account": "nobody",
"map to guest": "Bad User",
"username map cache time": "60"
}
}
}
Get Individual Authentication Configuration File
Send this request to get the contents of an individual authentication configuration file.
Request Object
+ URL
/api/v2/smb/auth/individual/:name/details
+ Method
GET
+ Parameters
name (string, required, URL param) - The name of the conf file you would like to retrieve.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{ }
Response Object
The contents of the individual authentication configuration file as raw and json outputs.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"raw": "workgroup = openlab\nrealm = openlab.com\nname resolve order = host wins bcast\nclient signing = if_required\nkerberos method = secrets and keytab\nsecurity = domain\ntemplate shell = /bin/false\ntemplate homedir = /home/%U\nidmap config openlab:backend = ad\nidmap config openlab:schema_mode = rfc2307\nidmap config openlab:range = 10000-999999\n",
"json": {
"workgroup": "openlab",
"realm": "openlab.com",
"name resolve order": "host wins bcast",
"client signing": "if_required",
"kerberos method": "secrets and keytab",
"security": "domain",
"template shell": "/bin/false",
"template homedir": "/home/%U",
"idmap config openlab:backend": "ad",
"idmap config openlab:schema_mode": "rfc2307",
"idmap config openlab:range": "10000-999999"
}
}
Create Individual Authentication Configuration File
Send this request to create a new individual authentication configuration file. This route should be used in conjunction with a request to set the global authentication configuration file if you wish for this new individual configuration file to be used in the SMB authentication process.
Request Object
+ URL
/api/v2/smb/auth/individual/create
+ Method
POST
+ Parameters
name (string, required, Body) - The name of the conf file you would like to create.
conf ([string, object], required, Body) - Can be either a string containing the raw text or an object representing the values that should be included into the individual conf file you are creating.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"name": "some_new_auth",
"conf": {
"workgroup": "openlab",
"realm": "openlab.com",
"name resolve order": "host wins bcast",
"client signing": "if_required",
"kerberos method": "secrets and keytab",
"security": "domain",
"template shell": "/bin/false",
"template homedir": "/home/%U",
"idmap config openlab:backend": "ad",
"idmap config openlab:schema_mode": "rfc2307",
"idmap config openlab:range": "10000-999999"
}
}
Update Individual Authentication Configuration File
Send this request to update one of the individual authentication configuration file.
Request Object
+ URL
/api/v2/smb/auth/individual/:name/update
+ Method
POST
+ Parameters
name (string, required, URL Param) - The name of the conf file you would like to update.
conf ([string, object], required, Body) - Can be either a string containing the raw text or an object representing the values that should be included into the individual conf file you are updating.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"conf": "workgroup = openlab\nrealm = openlab.com\nname resolve order = host wins bcast\nclient signing = if_required\nkerberos method = secrets and keytab\nsecurity = domain\ntemplate shell = /bin/false\ntemplate homedir = /home/%U\nidmap config openlab:backend = ad\nidmap config openlab:schema_mode = rfc2307\nidmap config openlab:range = 10000-999999\n"
}
Response Object
An output message, detailing success or error updating the individual configuration file.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"message": "Successfully set /etc/samba/smbauth.conf.d/some_new_auth.conf"
}
Delete Individual Authentication Configuration File
Send this request to delete one of the individual authentication configuration files.
Request Object
+ URL
/api/v2/smb/auth/individual/:name/delete
+ Method
POST
+ Parameters
name (string, required, URL Param) - The name of the conf file you would like to delete.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{ }
Response Object
An output message, detailing success or error deleting the individual configuration file.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"message": "Successfully removed /etc/samba/smbauth.conf.d/some_new_auth.conf"
}
List Authentication Configuration Templates
Send this request to list all of the authentication configuration templates on your system.
Request Object
+ URL
/api/v2/smb/auth/template
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The contents of each authentication template as raw text and json objects. This currently includes AD, LDAP, and Local.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"ad": {
"raw": "workgroup = $WORKGROUP\nrealm = $REALM\nname resolve order = host wins bcast\nclient signing = if_required\nkerberos method = secrets and keytab\nsecurity = domain\ntemplate shell = /bin/false\ntemplate homedir = /home/%U\nidmap config $WORKGROUP:backend = ad\nidmap config $WORKGROUP:schema_mode = rfc2307\nidmap config $WORKGROUP:range = 10000-999999\n",
"json": {
"workgroup": "$WORKGROUP",
"realm": "$REALM",
"name resolve order": "host wins bcast",
"client signing": "if_required",
"kerberos method": "secrets and keytab",
"security": "domain",
"template shell": "/bin/false",
"template homedir": "/home/%U",
"idmap config $WORKGROUP:backend": "ad",
"idmap config $WORKGROUP:schema_mode": "rfc2307",
"idmap config $WORKGROUP:range": "10000-999999"
}
},
"ldap": {
"raw": "workgroup = $WORKGROUP\nnetbios name = $NETBIOS\nrealm =\t$REALM\npassdb backend = ldapsam:ldap://$PASSDB_BACKEND\nldap suffix = $LDAP_SUFFIX\nldap admin dn = $LDAP_ADMIN_DN\nldap ssl = start tls\nldap passwd sync = yes\nidmap config $WORKGROUP : backend = ldap\nidmap config $WORKGROUP : schema_mode = rfc2307\nidmap config $WORKGROUP : range = 2000000-2999999\nidmap config $WORKGROUP : ldap_url = ldap://$PASSDB_BACKEND\nidmap config $WORKGROUP : ldap_base_dn = $LDAP_SUFFIX\n",
"json": {
"workgroup": "$WORKGROUP",
"netbios name": "$NETBIOS",
"realm": "$REALM",
"passdb backend": "ldapsam:ldap://$PASSDB_BACKEND",
"ldap suffix": "$LDAP_SUFFIX",
"ldap admin dn": "$LDAP_ADMIN_DN",
"ldap ssl": "start tls",
"ldap passwd sync": "yes",
"idmap config $WORKGROUP : backend": "ldap",
"idmap config $WORKGROUP : schema_mode": "rfc2307",
"idmap config $WORKGROUP : range": "2000000-2999999",
"idmap config $WORKGROUP : ldap_url": "ldap://$PASSDB_BACKEND",
"idmap config $WORKGROUP : ldap_base_dn": "$LDAP_SUFFIX"
}
},
"local": {
"raw": "auth methods = sam\npassdb backend = tdbsam\nguest account = nobody\nmap to guest = Bad User\nusername map cache time = 60\n",
"json": {
"auth methods": "sam",
"passdb backend": "tdbsam",
"guest account": "nobody",
"map to guest": "Bad User",
"username map cache time": "60"
}
}
}
Get Individual Authentication Configuration Template
Send this request to get an individual authentication configuration template.
Request Object
+ URL
/api/v2/smb/auth/template/:name/details
+ Method
GET
+ Parameters
name (string, required, URL Param) - The name of the configuration template you would like to retrieve.
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The contents of an authentication template as raw text and a json object.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"raw": "workgroup = $WORKGROUP\nnetbios name = $NETBIOS\nrealm =\t$REALM\npassdb backend = ldapsam:ldap://$PASSDB_BACKEND\nldap suffix = $LDAP_SUFFIX\nldap admin dn = $LDAP_ADMIN_DN\nldap ssl = start tls\nldap passwd sync = yes\nidmap config $WORKGROUP : backend = ldap\nidmap config $WORKGROUP : schema_mode = rfc2307\nidmap config $WORKGROUP : range = 2000000-2999999\nidmap config $WORKGROUP : ldap_url = ldap://$PASSDB_BACKEND\nidmap config $WORKGROUP : ldap_base_dn = $LDAP_SUFFIX\n",
"json": {
"workgroup": "$WORKGROUP",
"netbios name": "$NETBIOS",
"realm": "$REALM",
"passdb backend": "ldapsam:ldap://$PASSDB_BACKEND",
"ldap suffix": "$LDAP_SUFFIX",
"ldap admin dn": "$LDAP_ADMIN_DN",
"ldap ssl": "start tls",
"ldap passwd sync": "yes",
"idmap config $WORKGROUP : backend": "ldap",
"idmap config $WORKGROUP : schema_mode": "rfc2307",
"idmap config $WORKGROUP : range": "2000000-2999999",
"idmap config $WORKGROUP : ldap_url": "ldap://$PASSDB_BACKEND",
"idmap config $WORKGROUP : ldap_base_dn": "$LDAP_SUFFIX"
}
}
Get Local Authentication Information
Send this request to check if your system’s local SMB authentication information.
Request Object
+ URL
/api/v2/smb/auth/local
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
You will always get the response even though your system is bound to AD and AD authentication is enabled. This route returns the configuration that is currently stored in your system which will be used when you enable local authentication.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"passdb_backend": "tdbsam",
"guest_account": "nobody",
"map_to_guest": "Bad User",
"username_map_cache_time": "60"
}
Get AD Authentication Information
Send this request to check your domain’s information. You can check the domain name (realm) and workgroup that your system is bound.
Request Object
+ URL
/api/v2/smb/auth/ad
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
The response will show the Active Directory server’s workgroup and realm, which is your domain. This route returns a response if you have joined a domain at least once.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"workgroup": "OPENDRIVES",
"realm": "opendrives.com",
"idmap_config_OPENDRIVES:backend": "ad",
"idmap_config_OPENDRIVES:schema_mode": "rfc2307",
"idmap_config_OPENDRIVES:range": "10000-999999"
}
Enable Local Authentication
Send this request to enable local authentication. Enabling local authentication will prevent users from using other authentication methods to log in to the UI or mount SMB shares.
|
Deprecated
This route is slated for deprecation in Atlas version 2.6. We do not recommend using this route in any Atlas 2.4+ version. Using this route may alter the state of your Atlas system in unintended ways. Specifically, it will create a link between the global SMB authentication configuration file and a soon-to-be deprecated and unused local SMB authentication configuration file. Please do not use it. |
Enable AD Authentication
Send this request to enable Active Directory authentication.
|
Deprecated
This route is slated for deprecation in Atlas version 2.6. We do not recommend using this route in any Atlas 2.4+ version. Using this route may alter the state of your Atlas system in unintended ways. Specifically, it will create a link between the global SMB authentication configuration file and a soon-to-be deprecated and unused AD SMB authentication configuration file. Please do not use it. |
Join a Domain
Send this request to join a domain and mount SMB shares using the domain’s username and password. Sending this request will also enable AD authentication, so you don’t need to make additional /api/v2/smb/auth/ad/enable request.
|
Deprecated
This route is slated for deprecation in Atlas version 2.6. We do not recommend using this route in any Atlas 2.4+ version. Using this route may alter the state of your Atlas system in unintended ways. We recommend using |
Request Object
+ URL
/api/v2/smb/auth/ad/join
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{ }
Response Object
If successful, you will get a result showing the domain’s information.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"result": "Server:\t\t192.168.219.200\nAddress:\t192.168.219.200#53\n\nName:\tfuji.applefarm.local\nAddress: 192.168.219.191\nName:\tfuji.applefarm.local\nAddress: 172.17.0.1\n\n"
}
Leave a Domain
Send this request to leave a domain.
|
This request does not change SMB authentication automatically, so you must send Enable Local Authentication request after successfully making this request. |
Check AD Bind Status
Send this request to check if your system is joined to a domain.
Request Object
+ URL
/api/v2/smb/auth/ad/status
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"hostname": "fuji.applefarm.local"
}
Response Object
If your system is joined to the domain, result will show the domain’s IP address.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"result": "Server:\t\t192.168.219.200\nAddress:\t192.168.219.200#53\n\nName:\tfuji.applefarm.local\nAddress: 192.168.219.191\nName:\tfuji.applefarm.local\nAddress: 172.17.0.1\n\n"
}