NSR_DEVICE(5)

NAME
nsr_device - NetWorker resource type "NSR device"

SYNOPSIS
type: NSR device

DESCRIPTION
Each storage device used by a NetWorker server is described by a single resource of type NSR device. See nsr_resource(5) for information on NetWorker resources. To edit the NSR device resources run:
    nsradmin -c "type:NSR device"
Be sure to include quotation marks and to insert a space between "NSR" and "device". See nsradmin(8) for information on using the NetWorker administration program. The mounting and unmounting of individual volumes (tapes or disks) is performed using the nsrmm(8), nsrjb(8), and nwadmin(8) commands.

ATTRIBUTES

The following attributes are defined for resource type NSR device. The information in parentheses describes how the attribute values are accessed. Read-only indicates that the value cannot be changed by an administrator. Read/write indicates a value that can be set as well as read. Hidden indicates a hidden attribute of interest only to programs or experts. These attributes can only be seen when the hidden option is turned on in nsradmin(8), or if the Details View option is selected in the Media Devices window in nwadmin(8). Static attributes change values rarely, if ever. Dynamic attributes have values that change rapidly. For example, an attribute marked (read-only, static) has a value that is set when the attribute is created and never changes.

name 	(read-only, static)
    The name attribute specifies the path name of the device. Only non-rewinding tape devices are supported. For systems that support "Berkeley style" tape positioning,use the BSD tape device name. The name given to Optical disks is typically the name given to the "c" partition of the raw device.
    A logical device type has been defined to facilitate interaction with external media management services. When interacting with external media management services, the device name may be determined by the media management service associated with the device where a volume is loaded. The logical device is used to define a NetWorker device resource. The number of device resources that can exist is limited by the number of volumes managed by the service that NetWorker may access simultaneously. The name given to a logical device is not related to any specific device, but is required to be a unique name for the device. For logical devices both the media type and the family are set to logical. The name, type, and family are determined after the media management service has loaded a volume into a device in response to a request made by NetWorker. The name, type, and family of the actual device are then stored in the attributes logical name , logical type , and logical family , respectively. The association between the logical device and the actual device only exists when the volume is loaded into the device and allocated for use by NetWorker.
    When defining a remote device on a storage node, include the prefix "rd=hostname:", in the path name; where hostname is the system to which the device is directly attached (the storage node). For more information, see nsr_storage_node(5).
    Example: name: /dev/rmt/0hbn;

description 	(read/write)
    This attribute is used to store a brief description about the device. The description is used to help administrators identify the device, and it can be in any format.
    Example: description: DLT8000 tape drive in Engineerning Lab rack #2;

media type	(read-only, static)
    This attribute indicates the type of media a device uses. The media type varies depending on the Operating System/platform. Potential values, their meaning, and default capacities are:
    4mm - 4mm digital audio tape (1 GB); 8mm - 8mm video tape (2 GB); 8mm 5GB - 8mm video tape (5 GB); dlt - digital linear tape cartridge (10 GB); vhs - VHS data grade video tape (14 GB); 3480 - high-speed cartridge tape (200 MB); qic - quarter inch data cartridge (150 MB); himt - half inch magnetic tape (100 MB); tk50 - DEC TK50 cartridge tape (94 MB); tk70 - DEC TK70 cartridge tape (296 MB); optical - optical disks, Write Once Read Many (WORM), Erasable Optical Disks (EOD), or standard UNIX files are supported; file - file device type, standard UNIX file system is supported; logical - used when interacting with an external media management service.
    Example: media type: 8mm 5GB;

enabled	(read-write)
    This attribute indicates whether a device is available for use. The value for this attribute is either yes or no. If the value is set to no, no volumes may be mounted into the device. This value cannot be changed if a volume is mounted.
    Example: enabled: yes;

read only	(read-write)
    This attribute indicates whether a device is reserved for read only operations, such as recover or retrieve. The value for this attribute can be either yes or no. If the value is set to yes, only read operations are permitted on the device. This value cannot be changed if when the volume is mounted.
    Example: read only: yes;

target sessions			(read/write)
    This attribute indicates the target number of sessions that will write to a device. When all devices on a host have the same value for this attribute, sessions are assigned to a device, until the device's target sessions is reached; then sessions are assigned to the next device on the host. Once all devices have reached their target sessions, new sessions are assigned equally across all devices.
    When this attribute has different values for devices on a host, and the nsrmmd(8) has not yet been assigned to a device, then sessions are assigned to an nsrmmd(8) based on the lowest attribute value among the host's devices. Once the nsrmmd(8) is assigned to a device, the target sessions value for the assigned device is used.
    Use higher values to multiplex more clients onto each tape. This attribute is not a maximum number for a device, but is used for load-balancing.
    Example: target sessions: 3;

NDMP	(read-only)
    The NDMP attribute is used to note which devices are associated with NDMP servers. This attribute cannot be changed after the resource has been created. The resource must be deleted and recreated if the user needs to change this attribute for this device. The same username (remote user attribute) and password should be configured in the device resource as they are configured for the NDMP server.
    Example: NDMP: yes;

remote user		(read/write, string)
    The remote user attribute is used when the NDMP attribute is set to a value of yes. The value entered for this attribute should be the username configured for the NDMP server.
    Example: remote user: root;

password	(read/write, encrypted)
    This attribute is used in conjunction with the remote user attribute to configure access to a NDMP server.
    Example: password: ;

media family	(read-only, static, hidden)
    The media family attribute describes the class of storage media, as determined from the media type. The only legal values are: tape - tape storage device; disk - disk storage device; logical - used when interacting with an external media management service.
    Example: media family: tape;

message	(read-only, dynamic, hidden)
    This attribute specifies the last message received from the NetWorker server regarding this device. The values for this attribute may include information on the progress or rate of the operation.
    Example: message: "Tape full, mount volume mars.017 on /dev/nrst8";

volume name	(read-only, dynamic, hidden)
    This attribute monitors the mounting and unmounting of volumes for a device. When a volume is mounted, the value is the volume name, otherwise there is no value.
    Example: volume name: mars.017;

write enabled 	(read/write, dynamic, hidden)
    This attribute indicates whether writing to the current volume is allowed. The value for this attribute may be set to yes or no. This value can only be set when a volume is not mounted.
    Example: write enabled: no;

volume operation	(read/write, dynamic, hidden)
    The volume operation attribute manipulates the media (volume) currently located inside the device. This attribute can be set to one of the following values: Unmount, Mount, Verify label, Verify write time, Label, Label without mount, Eject, or Monitor device. Each of these operations may require parameters to be set.
    When the value is Unmount, NetWorker releases the device. The Unmount operation is asynchronous.
    When the value is Mount, NetWorker mounts the loaded volume into the device. The Mount operation is asynchronous.
    When the value is Verify label, the volume's label is read by NetWorker, and the attributes volume label and volume expiration are set. The Verify label operation is synchronous, and therefore the operation may take a long time to complete.
    When the value is Verify write time, the volume's label is read by NetWorker, and the attributes volume label, volume expiration, and volume write time are set. The Verify write time operation is synchronous, and therefore the operation may take a long time to complete.
    When the value is Label or Label without mount, the volume receives a new label as determined by the attributes below. When the value is Label, the volume is then mounted. These operations are asynchronous.
    When the value is Eject, NetWorker ejects the volume from the device. The Eject operation is asynchronous.
    When the value is Monitor device and the device is idle (no volume loaded into the device), NetWorker will periodically check the device to determine whether a volume has been loaded into the device. When a volume containing a readable NetWorker label is loaded, the volume is placed into the NetWorker media database. The volume can then be written to by NetWorker if the volume is mounted with write permissions turned on; otherwise, the volume is mounted as read only, and cannot be written to by NetWorker. When a volume without a readable NetWorker label is loaded into the device, the device's unlabeled volume loaded attribute is set to yes, and the volume may be labeled at a later date. The Monitor device operation is never performed on jukebox devices, because NetWorker only monitors non-jukebox devices.

volume label 	(read/write, dynamic, hidden)
    This attribute is set by the Verify label operation and can be performed before the Label operation. If this attribute is blank during the labeling process, then the volume's current label is reused.

volume default capacity	(read/write, static, hidden)
    This attribute is used by the Label operation when the volume current capacity attribute is blank. A non-blank value is used to override the default capacity associated with the media type. The value of this attribute must end with K, M, or G, where K represents Kilobytes, M represents Megabytes, and G represents Gigabytes.
    This hidden attribute can be modified by a user, and can be used to override default sizes when using devices (and/or tapes) with different capacities than the defaults.
    Example: To override the default capacity of a tape drive to 10 Gb for all future volume label operations, set the value as follows:
    volume default capacity: 10G;

volume current capacity	(read/write, dynamic, hidden)
    If the attribute's value is non-blank, it determines the capacity of a volume during the Label operation. Its format is the same as volume default capacity.
    Example: volume current capacity: 5G;

volume expiration 	(read/write, dynamic, hidden)
    This attribute is set by the Verify label operation and can also be used by the Label operation. The value for this attribute is specified in nsr_getdate(3) format. A blank value causes the default expiration to be used during labeling.
    Example: volume expiration: next year;

volume pool 	(read/write, hidden)
    This attribute indicates the pool that a mounted volume belongs to. If this attribute is set during a Label or Label without mount operation, this value will indicate the pool a volume is being assigned to. See nsr_pool(5) for more information on volume pools.
    Example: volume pool: Default;

NSR operation 	(read-only, dynamic, hidden)
    This attribute indicates the current operation being performed by a device. The valid values for this attribute are: Idle, Write, Read, Eject, Verify label, or Label.
    Example: NSR operation: Write;

minor mode 	(read-only, dynamic, hidden)
    This attribute indicates the current state of a device. The NSR operation attribute is the major mode. The valid values for this attribute are: idle, reading, writing, rewinding, moving forward, moving backward, error, done, writing eof, or finding eom.
    Example: minor mode: moving forward;

statistics 	(read-only, dynamic, hidden)
    This attribute reports the statistics for the operation of this device. The statistics include:
    the time of operation ("elapsed"), the number of errors ("errors"), the last writing rate ("last rate"), the max number of concurrent clients ("max clients"), the number of file marks written ("file marks"), the number of rewinds ("rewinds"), the number of files skipped ("files skipped"), the number of records skipped ("records skipped"), the current file number ("current file"), the current record number ("current record"), the relative nhumber of files being spaced over ("seek files"), the relative number of records being spaced over ("seek records"), the total estimated amount read/written on the volume, in KB ("estimated KB", to be implemented in a future release), the total amount read/written on the volume, in KB ("amount KB"), the current amount read/written on this file, in KB ("file amount KB"), and the current number of sessions assigned to this device ("sessions").

cleaning required	(read/write)
    This attribute indicates whether a device needs to cleaned. The value for this attribute may be either yes or no. If the value of this attribute changes from yes to no and the value of date last cleaned attribute is not updated, then the date last cleaned attribute is set to the current time. NetWorker might set this attribute to yes if at the time the device is next scheduled to be cleaned it is not available to be cleaned. In this case, the following message is displayed: device cleaning required . This message indicates that the device needs to be cleaned. This attribute can only be used for a device whose media family is tape and jukebox device is yes. For all other devices the value of this attribute is always no.

cleaning interval	(read/write)
    This attribute indicates the amount of time from the date last cleaned until the next scheduled cleaning for the device. This value can be specified in days, weeks, or months. One day, week, or month is implied if a number is not specified. If this attribute is set and date last cleaned is blank, date last cleaned is set to the current time. This attribute may only be used for a device whose media family is tape and jukebox device is yes.
    Example: cleaning interval: 2 weeks;

date last cleaned	(read/write)
    This attribute indicates the time and day a device was last cleaned. Input may be in any format acceptable to nsr_getdate(3). Some values acceptable to nsr_getdate(3) are relative, for example, now. For that reason all input is converted into ctime(3) format, weekday, month, day, time, year. As noted in the description of cleaning required and cleaning interval , the value of this attribute might be set automatically by NetWorker. This attribute can only be used for a device whose media family is tape and jukebox device is yes.

volume block size 	(read-only, dynamic, hidden)
    This attribute indicates the block size of the currently mounted volume.

volume id 	(read-only, dynamic, hidden)
    This attribute indicates the volume id for the currently mounted volume.

long volume id 	(read-only, dynamic, hidden)
    This attribute indicates the volume id for the currently mounted volume in the long globally unique format.

access count 	(read-only, dynamic, hidden)
    This attribute indicates the total number of operations performed on the device since it was configured as a NetWorker device.

access weight 	(read-only, dynamic, hidden)
    This attribute indicates the weight of a single operation performed on the device. The "access count" attribute will be incremented by "access weight" each time an operation performed on the device. The higher the weight, the less often the device will be selected for new operations.

consecutive errors 	(read-only, dynamic, hidden)
    This attribute indicates the current number of consecutive errors on a device.

max consecutive errors 	read-only, hidden)
    This attribute indicates the maximum number of consecutive errors allowed before disabling the device.

operation arg 	(read-only, dynamic, hidden)
    This attribute indicates extra parameters to be used during device operations. Parameters are packed into a string and parsed by the associated operation's function.

event tag 	(read/write, single number, hidden)
    This attribute contains the tag (unique identifier) of the last notification event sent to the nsrd (8) daemon. The tag is used to clear the previous event. This attribute is used to pass information between NetWorker programs, and should not be changed manually by the administrator.

volume message 	(read-only, dynamic, hidden)
    This attribute indicates the result of the last volume operation.

volume write time 	(read-only, dynamic, hidden)
    This attribute indicates the time that a save set was first written to the volume.

volume flags 	(read/write, hidden)
    This attribute displays the new flags for the volume being operated on. This attribute is used during "Label" or "Label without mount" operations.

jukebox device 	(read/write, dynamic, hidden)
    This attribute indicates the media device that is part of a jukebox device. This value can be either yes or no.

unlabeled volume loaded 	(read only, dynamic, hidden)
    This attribute indicates whether a volume loaded into the device has a readable NetWorker volume label. This value can be either yes or no. This attribute is set to yes when NetWorker is monitoring the device, a volume is loaded into the device, and the volume does not have a valid NetWorker label that can be read by this device. This attribute is set to no when the volume in the device is labeled or ejected from the device.

auto media management 	(read-write)
    This attribute indicates whether "automated media management" is enabled for a device. For jukebox devices this value is always no. See nsr_jukebox(5) for a description of auto media management for a jukebox. For non-jukebox devices, this value can be either yes or no. If this value is set to yes, then any recyclable volumes loaded into the device might be automatically re-labeled by NetWorker for re-use, and unlabeled volumes loaded into the device can be automatically labeled. When NetWorker is labeling a volume that is not expected to have a valid NetWorker label, it verifies that the volume is unlabeled before labeling the volume. A volume is considered to be unlabeled if the volume does not contain a label that may be read by this device.
    Note: If a volume contains a label, but the label is written at a density that cannot be read by the associated device, the volume is considered to be unlabeled. If the volume contains data written by an application other than NetWorker, it most likely does not have a label recognizable by NetWorker, and the volume is considered to be unlabeled. With this attribute enabled, care should be taken when loading any volume considered to be unlabeled or recyclable into the device. The volume might be re-labeled and the data previously on the volume over-written by NetWorker.
    When this attribute is set to yes for a device, and the device is idle (no tape loaded into the device), NetWorker will monitor the device and wait for a volume to be loaded. See the description of Monitor device in the discussion of the volume operation attribute.
    Example: auto media management: yes;

logical name 	(read-only, hidden, no create)
    This attribute indicates the name of the actual device associated with the logical device. This attribute is only used for logical devices.
    Example: logical name: /dev/rmt/0hbn;

logical type 	(read-only, hidden, no create)
    This attribute indicates the actual device type associated with the logical device. The values that can be associated with this attribute are the values that are valid for the attribute media type . The only exception is that the value of this attribute cannot be set to logical. This attribute is only used for logical devices.
    Example: logical type: 8mm 5GB;

logical family 	(read-only, hidden, no create)
    This attribute indicates the family of the actual device currently associated with the logical device. The values that can be associated with this attribute are the values that are valid for the attribute media family . The only exception is that the value of this attribute cannot be set to logical. This attribute is only used for logical devices.
    Example: logical family: tape;

connection process id 	(read only, hidden, no create)
    This attribute indicates the process identifier maintaining the connection with an external media management service.
    External media management services often require a connection to be maintained while an application is using allocated resources. If the connection is not maintained the service may attempt to reclaim any resources allocated to an application. This may include unloading a volume currently mounted into a device. Therefore, while NetWorker has a volume mounted into a device being managed by such a service, a process must maintain an open connection with the media management service.

connection message 	(read only, hidden, no create)
    This attribute records any error message(s) reported upon exit by a process maintaining a connection with an external media management service.

connection status 	(read only, hidden, no create)
    This attributes records the exit status reported by a process maintaining a connection with an external media management service. A status of zero indicates that the process exited successfully. A non-zero status indicates an error occured while the process was exiting.

save mount timeout 	(read/write, hidden, no create)
    This attribute indicates the timeout value for an initial save mount request for the storage node on which a device is located. If the request is not satisfied within the indicated time, the storage node will be locked from receiving save processes for the "save lockout" time. See nsr_storage_node(5) for a description of storage nodes. This attribute can be used for local devices as well, but "save lockout" cannot be changed from its default value of zero. Hence, local devices cannot be locked out from save requests.

save lockout 	(read/write, hidden, no create)
    This attribute indicates the number of minutes a storage node will be locked from receiving save assignments after it reaches the save mount timeout time during a save mount request. A value of zero indicates that the node will not be locked. This attribute cannot be changed for local devices.

autodetect id 	(read/write, hidden)
    This attribute is for identifying auto-detected devices. It is used by NetWorker programs only, and should not be changed manually by the administrator.

EXAMPLE

A complete example follows:
	type:	NSR device;
	name:	/dev/nrst8;
	message:	writing, done
	volume name:	mars.017;
	media family:	tape;
	media type:	8mm 5GB;
	enabled:	Yes;
	write enabled:	Yes;
	read only:	No;
	target sessions:	4;
	volume label:	mars.017;
	volume default capacity:	;
	volume current capacity:	5000 MB;
	volume expiration:	"Thu Sep 21 17:23:37 1996";
	volume pool:	Default;
	volume flags:	;
	volume operation:	;
	volume write time:	;
	volume block size:	32 KB;
	volume id:	32449;
	accesses:	199;
	access weight:	1;
	consecutive errors:	0;
	max consecutive errors:	20;
	operation arg:	;
	volume message:	;
	NSR operation:	;
	minor mode:	idle;
	jukebox device:	Yes;
	statistics:	elapsed = 257572, errors = 0, last rate = 397,
		max clients = 3, file marks = 22, rewinds = 4,
		files skipped = 1976, records skipped = 0,
		current file = 2389, current record = 162,
		seek files = 0, seek records = 0,
		estimated kb = 0, amount kb = 6273,
		file amount kb = 6273, sessions = 1;
	cleaning required:	No;
	cleaning interval:	2 weeks;
	date last cleaned:	"Tue Apr 11 15:10:32 1995";
	auto media management:	No;
	unlabeled volume loaded:	No;
	logical name:	;
	logical type:	;
	logical family:	;
	connection process id:	;
	connection message:	;
	connection status:	;
	save mount timeout:	30;
	save lockout:		0;

FILES
/nsr/res/nsr.res - this file should never be edited directly. Use nsrmm(8), nsradmin(8), or nwadmin(8) instead.

SEE ALSO
nsr_getdate(3), ctime(3), nsr_resource(5), nsr_pool(5), nsr_schedule(5), nsr_service(5), nsr_storage_node(5), nsr(8), nsrmmd(8), nsrmm(8), nsradmin(8), nwadmin(8).