s390-tools/zdsfs/zdsfs.1

.\" IBM Corporation Copyright 2013, 2017
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH ZDSFS 1 "2013" "s390-tools"

.SH NAME
zdsfs \- File system for z/OS data set access

.SH SYNOPSIS
.SS mounting:
.TP
\fBzdsfs\fP \fI<devices>\fR \fI<mountpoint>\fR [\fI<options>\fR]
.SS unmounting:
.TP
\fBfusermount\fP \-u \fI<mountpoint>\fR

.SH DESCRIPTION

Use the \fBzdsfs\fP command for read access to z/OS data sets
stored on one or more DASDs.

The zdsfs file system translates the record-based z/OS data sets to
UNIX file system semantics.  After mounting the devices, you can use
common Linux tools to access the files on the disk. Physical
sequential data sets are represented as files. Partitioned data sets
are represented as directories, with each member being represented as
a file in that directory.

.SH RESTRICTIONS
Only read access is supported.

Data sets on tape devices are not supported.

If the z/OSMF REST services are not used for a coordinated-read
access, access to the device by Linux is not subject to RACF or any
other z/OS auditing mechanism. Ensure the security of the data on the
device by using the well-known Linux methods. By default, zdsfs grants
access to the files in the fuse file system only to the user who
started the tool. Configure file access behavior by using the
‘allow_other’, ‘default_permissions’, ‘umask’, ‘uid’, and ‘gid’
options.

When using the z/OSMF REST services for coordinated read access, every
file open establishes a connection to the z/OSMF REST server. This
checks that the accessing z/OS user ID has the appropriate access
rights for the data set. Using this mechanism, an exclusive ENQ is
obtained that marks the data set as in-use to z/OS. An ENQ is a z/OS
method to control a serially reusable resource. While the ENQ is held,
no z/OS application can modify the data set. If the ENQ cannot be
obtained, the access attempt from Linux fails.

Only physical sequential (PS) and partitioned data sets (PDS) are
supported. Supported record formats are: V, F, U, B, S, A, and M.

The file system is limited to basic operations: readdir, stat, open,
read, and seek. Because the actual size of the data in each track is not
always known, zdsfs does not support mmap. Seek operations read the
whole data set to the given offset. The performance of seek
operations to previous offsets can be improved by buffering seek
offsets, see option `\-o seekbuffers'.

A further consequence of the unknown exact data size is that zdsfs
cannot provide exact file sizes. As a heuristic, the given file sizes
are the maximum possible data sizes, based on the number and size of
the extents that belong to each data set. When the actual end of the
data is reached during read, the usual end of file (EOF) is returned.
To ensure that the EOF is passed to the user correctly, the option
`\-o direct_io' is set by zdsfs implicitly.

Incomplete multi-volume data sets are not detected if only the first
volume (device) of the data set is present.

.SH OPTIONS
.SS "general options:"

.TP
\fB<devices>\fR One or more DASD device nodes, where node specifications are
separated by blanks. The device nodes can be specified explicitly with
the command or with the \-l option and a file.
.TP
\fB<mountpoint>\fR The mount point for the specified DASD.
.TP
\fB\-o\fR \fI<opt>\fR,[\fI<opt>\fR...]  Fuse or mount command
options. For fuse options see "Applicable FUSE options" below, for
mount options see \fBmount(8)\fP.
.TP
\fB\-h\fR or \fB\-\-help\fR
Print usage information, then exit.
.TP
\fB\-v\fR or \fB\-\-version\fR
Print version information, then exit.
.SS "zdsfs options:"
.TP
\fB\-l\fR \fI<device_list>\fR
The specified file \fI<device_list>\fR contains a list of device
nodes, separated by white space (space, tab or new line). All device
nodes in this file are mounted as if specified directly via the command
line.
.TP
\fB\-o\fR rdw
Keep record descriptor words in the byte stream. By default, data set
files contain only the user data.

Record boundaries might be important for applications to correctly
interpret the user data. For data sets with variable records, the
record descriptor words are required to find the record
boundaries. With fixed blocks, record boundaries can be computed from
the fixed record sizes.

See `z/OS DFSMS Using Data Sets' for more information about record
descriptor words.
.TP
\fB\-o\fR ignore_incomplete
Continue processing even if parts of a multi-volume data set are
missing.  By default, zdsfs ends with an error unless all data sets
are complete.

Incomplete data sets can be tolerated, for example, if all data of
interest is on another data set that is complete.
Incomplete data sets are not represented in the file system. Instead,
for each incomplete data set, a warning message is written to the
standard error stream.
.TP
\fB\-o\fR tracks=\fI<n>\fR
Size of the track buffer in tracks. The default for \fI<n>\fR is 128.

The data that is read from the DASD must be stored in a buffer, because
the minimum size for a read operation in raw access mode is one track,
and the user data must be extracted from the track images.  Reading
more than one track at a time improves the overall performance, but
requires larger buffers.

The memory needed by zdsfs for buffering a single track is 64KB for the
raw track data and 56KB for the extracted user data. Each time a file
is opened a total of (\fI<n>\fR * 120KB) is allocated for the track buffer.

.TP
\fB\-o\fR seekbuffer=\fI<s>\fR
Upper limit in bytes for the seek history buffer size. The default for
\fIs\fR is 1048576.

Because the block and record sizes in a data set may vary,
the only way to find a data byte at a particular offset (`seek') is
to read and interpret the whole data set from the beginning, until
the offset is reached.

To improve the performance of `seek' operations in areas that have
already been read, zdsfs can buffer offsets in regular
intervals. These intervals are multiples of \fI<n>\fR tracks, as specified
with the `tracks' option.

For small data sets and large values of \fI<n>\fR, only a few seek offsets
need to be buffered. In this case, the amount of memory that is
actually allocated can be much smaller than the upper limit \fI<s>\fR.

If \fI<s>\fR is set to 0, no seek history buffer is allocated. In this
case `seek' is still supported, but a `seek' operation might result in a
read from the beginning of the data set.

.TP
\fB\-o\fR check_host_count
Stop processing if the device is used by another operating system
instance.

.TP
\fB\-c\fR \fI<config_file>\fR
Provide a configuration file for zdsfs. The default is /etc/zdsfs.conf.

.TP
\fB\-o\fR restapi
Use z/OSMF REST services for coordinated read-access to data sets. The
user credentials are read from the .netrc file in the user's home
directory, or from the location the NETRC environment variable points
to.

.TP
\fB\-o\fR restserver=<server_URL>
Specify up to three server URLs to z/OSMF REST services. If more than
one server is specified, the first that responds is used. If a server
does not respond any longer during operation all specified server are probed again.

.TP
\fB\-x\fR \fI<dataset_file>\fR
Use a config file with code-page conversion options for
specific data sets.

.TP
\fB\-o\fR codepage_convert
Enable code-page conversion for all data sets. Unless specified
otherwise, the source code-page is EBCDIC CP1047 and the target
code-page is UTF-8.

You can change the default for the source code-page with the -o
codepage_from option and for the target code-page with the -o
codepage_to option. To specify source and target code-pages for
individual data sets use a data set config file.

.TP
\fB\-o\fR codepage_from=\fI<n>\fR
Override EBCDIC CP1047 as the default code-page for the source. Must
be combined with \fB\-o\fR codepage_to=\fI<n>\fR. Overrides settings
in a data set config file. Issue iconv \-l for a list of valid
specifications for <n>.

.TP
\fB\-o\fR codepage_to=\fI<n>\fR
Override UTF-8 as the default code-page for the target. Must be
combined with \fB\-o\fR codepage_from=\fI<n>\fR. Overrides settings
in a data set configu file. Issue iconv \-l for a list of valid
specifications for <n>.

.SS "Applicable FUSE options (version 2.8):"
This is a selected subset of all FUSE options. Use the zdsfs
\fB\-\-help\fR option to print a full list.

.TP
\fB\-d\fR or \fB\-o\fR debug
Enable debug output (implies \fB\-f\fR)
.TP
\fB\-f\fR
Foreground operation
.TP
\fB\-o\fR allow_other
Allow access by other users
.TP
\fB\-o\fR allow_root
Allow access by root
.TP
\fB\-o\fR default_permissions
Enable permission checking by kernel
.TP
\fB\-o\fR max_read=\fI<n>\fR
Set maximum size of read requests
.TP
\fB\-o\fR kernel_cache
Cache files in kernel
.TP
\fB\-o\fR [no]auto_cache
Enable caching based on modification times
.TP
\fB\-o\fR umask=\fI<m>\fR
Set file permissions (octal)
.TP
\fB\-o\fR uid=\fI<m>\fR
Set file owner
.TP
\fB\-o\fR gid=\fI<n>\fR
Set file group
.TP
\fB\-o\fR max_readahead=\fI<n>\fR
Set maximum readahead
.TP
\fB\-o\fR async_read
Perform reads asynchronously (default)
.TP
\fB\-o\fR sync_read
Perform reads synchronously


.SH DATA SET CHARACTERISTICS

Certain data set characteristics might be required for the correct
interpretation of the data. The collected metadata of all data sets
can be found in a file `metadata.txt' in the top directory of the
mounted file system.

This file contains one line per data set, with the syntax that is used
by z/OS.

dsn=<data set name>,recfm=<fmt>,lrecl=<size>,dsorg=<org>

\fBdsn\fR: The data set name.
For physical sequential data sets, this is the same as the file name in the mount directory. For partitioned
data sets (PDS), this is the same as the directory name in the mount
directory. For PDS members, the member name is placed after the PDS
name, in parentheses.

\fBrecfm\fR: The record format.

\fBlrecl\fR: The logical record length.

\fBdsorg\fR: The data set organization.
For partitioned data sets the organization is `PO', but for
partitioned data set members it is `PS'.

In addition to the `metadata.txt' file, you can use the following
extended attributes to read the data set characteristics of a file or
directory:

\fBuser.recfm\fR: The record format.

\fBuser.lrecl\fR: The logical record length.

\fBuser.dsorg\fR: The data set organization of a file.

.SH zdsfs config file

The default path is /etc/zdsfs.conf. Specify a different zdsfs config
file location with the \fB\-c\fR \fI<config_file>\fR option.
.br
The config file may contain the following options:
.PP

.B restapi
=
.IR 0 / 1
.IP
Determines whether the z/OSMF REST services should be used. If
enabled, a valid REST server must be specified, as well as a .netrc
file with a valid z/OS user ID and password.
.PP

.B restserver
=
.IR URL
.IP
Specifies the address of the z/OSMF REST server that is used for
coordinating read-access. For failover scenarios, provide up to three
different server addresses. These will be tried in the specified order
when one of the servers cannot be reached during mount or operation.
.PP

.B keepalive
=
.I timeout (in seconds)
.IP
Optionally change the keepalive timer for ENQs. By default the
keepalive refreshes the access after 540 seconds (9 minutes).The 9
minutes are chosen to prevent a timeout by z/OS after 10 minutes.

.SH data-set config file <dataset_file>
Provides code-page conversion settings for individual data sets.
The default config file is /etc/zdsfs-dataset.conf. Use the \fB\-x\fR
\fI<dataset_file>\fR option to specify a different file.
.br
Each config-file entry must contain the following options:
.PP

.B
DATASET.TITLE
.IP
Specifies the data-set title or a pattern of titles to which the entry
applies. The title can have a trailing asterisk to match all titles
that begin with the leading characters.
.PP

.B conv
=
.IR 0 / 1 / <codepage_from>,<codepage_to>
.IP
\fI0\fR disables code-page conversion.
.br
\fI1\fR performs conversion with the default conversion table.
.br
An explicit specification of source and target code-page overrides the default conversion tables
The code-page specifications must be separated by a comma.
Issue iconv \-l for a list of valid code-page specifications.

.PP

.B rdw
=
.I 0 / 1
.IP
\fI0\fR omits the record descriptor word from the data stream.
.br
\fI1\fR keeps the record descriptor word from the data stream.
.br
Code-page conversion can render data unreadable if the record descriptor word is kept.


.SH EXAMPLES
To mount the z/OS disk with the name dasde enter:
.br

  # zdsfs /dev/dasde /mnt

.br

To mount the z/OS disk with space for 4 tracks and keeping the record
descriptor words in the byte stream, enter:
.br

  # zdsfs \-o rdw \-o tracks=4 /dev/dasde /mnt

.br

To unmount the z/OS disk mounted on /mnt enter:
.br

  # fusermount \-u /mnt

To list all extended attributes of file FOOBAR.TEST.TXT
assuming the z/OS disk was mounted on /mnt:

  # getfattr \-d /mnt/FOOBAR.TEST.TXT
.br

To mount the z/OS disk using the z/OSMF REST services for coordinated
read access:

 # ./zdsfs \-o restapi \-o restserver=zos1.server.tld/zosmf /dev/dasde /mnt/

.br
To mount the z/OS disk and enable code-page conversion for all data
sets using a custom source and target code page:

  # ./zdsfs \-o codepage_from=CP037 \-o codepage_to=ISO\-8859\-1 /dev/dasde /mnt/


.SH SEE ALSO
getfattr(1), fuse(8), z/OS DFSMS Using Data Sets,
and Linux on System z: Device Drivers, Features and Commands