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 or directory to be the target of the operation. This is required and must consist of a fully qualified path and file or directory name.

Custom 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

X-IBM-Target-System = <string>

This header indicates the target system name (nick name) for this request, where the system name (nick name) is defined in the local system Systems table. The target host system must support single-sign-on by using either an LTPA token or a valid X-IBM-Target-System-User and X-IBM-Target-System-Password is provided for the target system. If the target system is the local system, this header is ignored and has no effect. End of change

X-IBM-Target-System-User

This header indicates the z/OS user ID that allows the user to access the target system. If the X-IBM-Target-System header is not supplied, this header is ignored. Both X-IBM-Target-System-Password and X-IBM-Target-System-User must be provided together; otherwise, this header is ignored.

If this header is not provided in the current request, the current request uses the authenticated user credentials to access the target system if either of the following conditions are true:

The X-IBM-Target-System-User header was provided in a previous request
The service described in Authenticate with a secondary z/OSMF instance was issued in a previous request.

X-IBM-Target-System-Password

This header indicates the password that is associated with the z/OS user ID. If the X-IBM-Target-System header is not supplied, this header is ignored. Both X-IBM-Target-System-Password and X-IBM-Target-System-User must be provided together; otherwise, this header is ignored. End of change

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, which is 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 is tagged as specified in the "type" keyword. If "remove", any existing file tag is 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 be specified only when the action is "set".	No
	codeset	Specifies the coded character set in which text data is encoded, such as ASCII or EBCDIC. For example, the code set for ASCII is ISO8859-1; the code set for EBCDIC is IBM-1047.	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 is checked to try to determine the type. This is not required.
	overwrite:true\|false	The default is true. May not be specified with 'from-dataset'.	No
	recursive:true\|false	The default is false. When 'true', copies all the files and subdirectories that are 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 that are specified as source file or 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 source file. (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 is supplied to allow automatic conversion. If the from-dataset/type attribute is not specified, no "-O u" switch is 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 or directory to be moved.	Yes
	overwrite:true\|false	The default is true. May not be specified with 'from-dataset'.	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 happens 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 that is specified in 'entries', it is created. If an ACL entry exists for a user or group that was specified in 'entries', it is replaced. Note: The 'modify' keyword cannot be specified with 'delete-type' or 'set'.	No
	delete	Deletes the extended ACL entries that are 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, no error is issued. 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"}