z/OS UNIX file utilities

You can use the z/OS UNIX file utilities to operate on a Unix System Services file or directory. Operations include: chmod, chown, chtag, copy, extattr, getfacl, move and setfacl.

HTTP method and URI path

PUT /zosmf/restfiles/fs/<file-path-name>

where:

/zosmf/restfiles specifies the z/OS® data set and file REST interface
/fs indicates a Unix System Services file system request
<file-path-name> identifies the UNIX file/directory to be the target of the operation. This is required and must consist of a fully qualified path and file/directory name.

Headers

X-IBM-BPXK-AUTOCVT

This header is optional; use it to indicate how file auto conversion is handled when using the copy operation to copy text mode data sets to POSIX files, if you omit this header, the system default is taken.

'on' or 'all': The target file is a candidate for automatic conversion if its TXTFLAG is tagged TEXT and the source data set is type TEXT.
'off': The target file is not a candidate for automatic conversion

The header, Content-Type: application/json; charset={charset-name}, must be specified as well.

Request body

A JSON request document (content-type=application/json, character-encoding=UTF-8) must be supplied in one of the following forms:

Table 1. JSON request document
Function	Property	Description	Required
chmod	request	Indicates the function chmod.	Yes
	mode	The mode value, specified as the POSIX symbolic form or octal value (as a JSON string).	Yes
	links:"follow\|suppress"	The default is 'follow' encountered links. This applies a mode change to the file or directory pointed to by any encountered links. 'suppress' is a mode change for the file or directory pointed to by any encountered symbolic links.	No
	recursive:true\|false	The default is false. When 'true', the file mode bits of the directory and all files in the file hierarchy below it are changed. (chmod -R).	No
chown	request	Indicates the function chown.	Yes
	owner	The user ID or UID (as a JSON string).	Yes
	group	The group ID or GID (as a JSON string).	No
	links:"follow\|change"	The default is 'follow'. 'change' does not follow the link, but instead changes the link itself (chown -h).	No
	recursive:true\|false	The default is false. When 'true', changes all the files and subdirectories in that directory to belong to the specified owner (and group, if :group is specified).chown -R)	No
chtag	request	Indicates function chtag.	Yes
	action:"set\|remove\|list"	The file tag action. If "set", the file will be tagged as specified in the "type" keyword. If "remove", any existing file tag will be removed. If "list", the existing tag information will be returned in a JSON response document. See "list action.	Yes
	type:"binary\|mixed\|text"	The default is "mixed" This option can only be specified if the action is "set".	No
	codeset	The default is 'follow'. 'change' does not follow the link, but instead changes the link itself (chown -h).	No
	links:"change\|suppress"	The default is 'change' encountered links, applying a tag action to the file or directory pointed to by any encountered links. 'suppress' a tag action for the file or directory pointed to by any encountered	No
	recursive:true\|false	The default is false. When 'true', tags all the files and subdirectories in that directory (chtag -R).	No
Note: If the 'list' action is specified, a response json document is returned listing the current tag information, For example: `{"stdout":["m ISO8859-1 T=off /tmp/file"]}` The -q and -v options are not supported.
copy	request	Indicates the function copy.	Yes
	from:`file-or-directory`	The file or directory to copy.	You can use either from:`file-or-directory` or from-dataset.
	from-dataset	dsn The fully qualified data set name. This is required.
		member The data set member to copy. This is not required.
		type One of "binary \| executable \| text". If not specified, the format of the data set will be checked to try to determine the type. This is not required.
	overwrite:true\|false	The default is true.	No
	recursive:true\|false	The default is false. When 'true', copies all the files and subdirectories specified by source into a directory (cp -R). May not be specified with 'from-dataset'.	No
	links:"none\|src\|all"	The default is none. When 'src', follows symbolic links specified as source file/directory (cp -H). When 'all', follows symbolic links specified as source file/directory and those encountered in the tree traverse (cp -L). Cannot be specified with 'from-dataset'.	No
	preserve: "none\|modtime\|all"	The default is none, sets the modification time of the destination file to the present. When 'modtime', sets the modification and access time of each destination file to that of the corresponding sourcefile. (cp -m). When 'all', preserves the modification and access times as well as the file mode, file format, owner, and group owner (cp -p). May not be specified with 'from-dataset'.	No
Note: When from-dataset/type == text, and the header X-IBM-BPXK-AUTOCVT == ON \| ALL,the cp "-O u" switch will be supplied to allow automatic conversion. If the from-dataset/type attribute is not specified, then no "-O u" switch will be applied and automatic conversion will not be available.
extattr	request	Indicate the function extattr.	Yes
	set:”attrs”	One or more of the following: alps.	No
	reset:”attrs”	One or more of the following: alps.	No
Note: If neither set or reset are provided, a response json document is returned listing the attributes, For example: `{ "stdout": ["/etc/inetd.conf", "APF authorized = NO", "Program controlled = NO", "Shared address space = YES", "Shared library=NO"] }` The -F option is not supported.
getfacl	request	Indicates the function getfacl.	Yes
	type:"access\|dir\|file"	The default is 'access', displays the access ACL entries for a file or directory (getfacl -a). 'dir' displays the directory default ACL entries (getfacl -d). If the target is not a directory, a warning is issued.	No
	user	The user ID or UID (as a JSON string), displays only the ACL entries for the specified types of access control lists (getfacl -a, -d, -f) which affects the specified user's access (getfacl -e user).	No
	use-commas:true\|false	The default is 'false'. When true, displays each ACL entry,using commas to separate the ACL entries instead of newlines.	No
	suppress-header:true\|false	The default is 'false'. When true, the comment header (the first three lines of each file's output) is not to be displayed (getfacl -m).	No
	suppress-baseacl:true\|false	The default is 'false'. When true, displays only the extended ACL entries. Does not display the base ACL entries (getfacl -o).	No
Note: On completion of this request, a response json document is returned, For example: `{"stdout":["#file: /etc/inetd.conf","#owner: CFZSRV","#group: SYS1","user::rwx", "group::rwx","other::rwx"]}`
move	request	Indicates the function move.	Yes
	from	The file/directory to move.	Yes
	overwrite:true\|false	The default is true.	No
setfacl	request	Indicates the function setfacl.	Yes
	abort:true\|false	The default is false. When true, aborts processing if an error or warning occurs. See the setfacl command documentation for complete documentation on the errors and warnings (setfacl -a).	No
	links:"follow\|suppress"	The default is 'follow'. 'suppress' does not follow symbolic links. Because ACLs are not associated with symbolic links, nothing will happen if a symbolic link is encountered (setfacl -h). Note: At least one of the following four keywords must be specified. 'modify' and 'delete' may both be specified, but not with 'delete-type' and 'set'.	No
	delete-type	Delete all extended ACL entries by type (setfacl -D type): access Access ACL dir Directory default ACL file File default ACL every Every extended ACL for all ACL types that are applicable for the current path name. Note: The 'delete-type' keyword cannot be specified with 'set', 'modify' or 'delete'.	No
	set	sets (replaces) all ACLs with 'entries'. 'entries' represents a string of ACL entries. Refer to the setfacl command reference for the string format (setfacl -s entries). Note: The 'set' keyword cannot be specified with 'delete-type', 'modify' or 'delete'.	No
	modify	Modifies the ACL entries. 'entries' represents a string of ACL entries. Refer to the setfacl command reference for the string format. If an ACL entry does not exist for a user or group specified in 'entries', then it is created. If an ACL entry already exists for a user or group that was specified in 'entries', then it is replaced. Note: The 'modify' keyword cannot be specified with 'delete-type' or 'set'.	No
	delete	Deletes the extended ACL entries specified by 'entries'. 'entries' is a string of ACL entries. Refer to the setfacl command reference for the string format. If an ACL entry does not exist for the user or group specified, then you will not get an error. Note: The 'delete' keyword cannot be specified with 'delete-type' or 'set'.	No

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 OK indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

For errors, the HTTP response includes error information as a JSON error report document. See Error report document.

Example

Refer to Figure 1 for an example of renaming a UNIX file.

Figure 1. Example: Rename a UNIX file

Example request for renaming /etc/inetd.conf to /etc/inetd.conf.bak:

PUT https://zosmf1.yourco.com/zosmf/restfiles/fs/etc/inetd.conf.bak HTTP/1.1
Content-Type: application/json; charset=UTF-8

{"request":"move", "from":"/etc/inetd.conf"}