Page MenuHomeFreeBSD
Differential D9299 Diff 42352 usr.sbin/ctladm/ctladm.8

Changeset View

Standalone View

View Options

usr.sbin/ctladm/ctladm.8

.\" .\"
.\" Copyright (c) 2003 Silicon Graphics International Corp. .\" Copyright (c) 2003 Silicon Graphics International Corp.
.\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org> .\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
.\" Copyright (c) 2018 Marcelo Araujo <araujo@FreeBSD.org>
.\" All rights reserved. .\" All rights reserved.
.\" .\"
.\" Redistribution and use in source and binary forms, with or without .\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions .\" modification, are permitted provided that the following conditions
.\" are met: .\" are met:
.\" 1. Redistributions of source code must retain the above copyright .\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions, and the following disclaimer, .\" notice, this list of conditions, and the following disclaimer,
.\" without modification. .\" without modification.
Show All 18 Lines
.\" .\"
.\" ctladm utility man page. .\" ctladm utility man page.
.\" .\"
.\" Author: Ken Merry <ken@FreeBSD.org> .\" Author: Ken Merry <ken@FreeBSD.org>
.\" .\"
.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $ .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd July 15, 2017 .Dd Apr 13, 2018
.Dt CTLADM 8 .Dt CTLADM 8
.Os .Os
.Sh NAME .Sh NAME
.Nm ctladm .Nm ctladm
.Nd CAM Target Layer control utility .Nd CAM Target Layer control utility
.Sh SYNOPSIS .Sh SYNOPSIS
.Nm .Nm
.Aq Ar command .Aq Ar command
▲ Show 20 Lines • Show All 109 Lines • ▼ Show 20 Lines
.Aq Fl s Ar size_bytes .Aq Fl s Ar size_bytes
.Nm .Nm
.Ic devlist .Ic devlist
.Op Fl b Ar backend .Op Fl b Ar backend
.Op Fl v .Op Fl v
.Op Fl x .Op Fl x
.Nm .Nm
.Ic port .Ic port
.Op Fl c
.Op Fl o Ar on|off .Op Fl o Ar on|off
.Op Fl w Ar wwpn .Op Fl w Ar wwpn
.Op Fl W Ar wwnn .Op Fl W Ar wwnn
.Op Fl O Ar pp|vp
.Op Fl p Ar targ_port .Op Fl p Ar targ_port
.Op Fl r Ar targ_port
.Op Fl t Ar fe_type .Op Fl t Ar fe_type
.Nm .Nm
.Ic portlist .Ic portlist
.Op Fl f Ar frontend .Op Fl f Ar frontend
.Op Fl i .Op Fl i
.Op Fl l .Op Fl l
.Op Fl p Ar targ_port .Op Fl p Ar targ_port
.Op Fl q .Op Fl q
▲ Show 20 Lines • Show All 412 Lines • ▼ Show 20 Lines
or or
.Fl w .Fl w
or or
.Fl W .Fl W
must be specified. must be specified.
The WWNN and WWPN may both be specified at the same time, but cannot be The WWNN and WWPN may both be specified at the same time, but cannot be
combined with enabling/disabling or listing ports. combined with enabling/disabling or listing ports.
.Bl -tag -width 12n .Bl -tag -width 12n
.It Fl c
Create new frontend port using free pp and vp=0.
wblockUnsubmitted
Done
Inline Actions

This reads better with s/Creates/Create/.

wblock: This reads better with s/Creates/Create/.
mavUnsubmitted
Not Done
Inline Actions

"ioctl" frontend here used only as default. There is a -d perameter to allow overriding. At least iscsi ports can also be created now, just not recommended (and pointless) to do that manually without ctld.

mav: "ioctl" frontend here used only as default. There is a -d perameter to allow overriding. At…
.It Fl o Ar on|off .It Fl o Ar on|off
Turn the specified CTL frontend ports off or on. Turn the specified CTL frontend ports on or off.
If no port number or port type is specified, all ports are turned on or If no port number or port type is specified, all ports are turned on or
off. off.
.It Fl O Ar pp|vp
Specify generic options on the ioctl frontend port.
wblockUnsubmitted
Done
Inline Actions

s/Creates/Create/

wblock: s/Creates/Create/
mavUnsubmitted
Done
Inline Actions

Description of "-c" and "-O" options is confusing. Somebody may think that "-O" will create something by itself, that is IIRC incorrect. IIRC "-c" just means "create", while "-O" is used to pass arbitrary options, of which we have now pp and vp.

mav: Description of "-c" and "-O" options is confusing. Somebody may think that "-O" will create…
At present, only pp and vp port numbers can be set.
.It Fl p Ar targ_port .It Fl p Ar targ_port
Specify the frontend port number. Specify the frontend port number.
The port numbers can be found in the frontend port list. The port numbers can be found in the frontend port list.
.It Fl r
Remove port specified with
wblockUnsubmitted
Done
Inline Actions

This is a little weird with the "if". -p targ_port is required for this, right? So maybe:

Remove port.
Port must be specified with
.Pq Fl p Ar targ_port .
wblock: This is a little weird with the "if". -p targ_port is required for this, right? So maybe…
mavUnsubmitted
Done
Inline Actions

I agree. I would just possibly tell shorter:
Remove port specified with
.Pq Fl p Ar targ_port .

mav: I agree. I would just possibly tell shorter: Remove port specified with .Pq Fl p Ar targ_port .
.Pq Fl p Ar targ_port .
.It Fl t Ar fe_type .It Fl t Ar fe_type
Specify the frontend type. Specify the frontend type.
Currently defined port types are Currently defined port types are
.Dq fc .Dq fc
(Fibre Channel), (Fibre Channel),
.Dq scsi .Dq scsi
(Parallel SCSI), (Parallel SCSI),
.Dq ioctl .Dq ioctl
▲ Show 20 Lines • Show All 334 Lines • ▼ Show 20 Lines
Options specific for ramdisk backend: Options specific for ramdisk backend:
.Bl -tag -width 12n .Bl -tag -width 12n
.It Va capacity .It Va capacity
Specifies capacity of backing store (maximum RAM for data). Specifies capacity of backing store (maximum RAM for data).
The default value is zero, that disables backing store completely, The default value is zero, that disables backing store completely,
making all writes go to nowhere, while all reads return zeroes. making all writes go to nowhere, while all reads return zeroes.
.El .El
.Sh EXAMPLES .Sh EXAMPLES
.Dl ctladm tur 1
.Pp .Pp
Send a Send a
.Tn SCSI .Tn SCSI
TEST UNIT READY command to LUN 1. TEST UNIT READY command to LUN 1.
.Pp .Pp
.Dl ctladm modesense 1 -l .Dl ctladm tur 1
.Pp .Pp
Display the list of mode pages supported by LUN 1. Display the list of mode pages supported by LUN 1.
.Pp .Pp
.Dl ctladm modesense 0 -m 10 -P 3 -d -c 10 .Dl ctladm modesense 1 -l
.Pp .Pp
Display the saved version of the Control mode page (page 10) on LUN 0. Display the saved version of the Control mode page (page 10) on LUN 0.
Disable fetching block descriptors, and use a 10 byte MODE SENSE command Disable fetching block descriptors, and use a 10 byte MODE SENSE command
instead of the default 6 byte command. instead of the default 6 byte command.
.Bd -literal
ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
.Ed
.Pp .Pp
.Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
.Pp
Read the first 512 byte block from LUN 2 and dump it to the file Read the first 512 byte block from LUN 2 and dump it to the file
.Pa foo .
.Bd -literal .Bd -literal
ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar .Dl ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
.Ed .Ed
.Pp .Pp
Read 10240 bytes from the file Read 10240 bytes from the file
.Pa /tmp/bar .Pa /tmp/bar
and write it to LUN 3. and write it to LUN 3.
starting at LBA 0xff432140. starting at LBA 0xff432140.
.Pp .Pp
.Dl ctladm create -b ramdisk -s 10485760000000000 .Bd -literal
.Dl ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
.Ed
.Pp .Pp
Create a LUN with the Create a LUN with the
.Dq fake .Dq fake
ramdisk as a backing store. ramdisk as a backing store.
The LUN will claim to have a size of approximately 10 terabytes, The LUN will claim to have a size of approximately 10 terabytes,
while having no real data store (all written data are lost). while having no real data store (all written data are lost).
.Pp .Pp
.Dl ctladm create -b ramdisk -s 10T -o capacity=10G .Dl ctladm create -b ramdisk -s 10485760000000000
.Pp .Pp
Create a thin provisioned LUN with a ramdisk as a backing store. Create a thin provisioned LUN with a ramdisk as a backing store.
The LUN will have maximal backing store capacity of 10 gigabytes, The LUN will have maximal backing store capacity of 10 gigabytes,
while reporting size of 10 terabytes, while reporting size of 10 terabytes,
.Pp .Pp
.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 .Dl ctladm create -b ramdisk -s 10T -o capacity=10G
.Pp .Pp
Create a LUN using the block backend, and specify the file Create a LUN using the block backend, and specify the file
.Pa src/usr.sbin/ctladm/ctladm.8 .Pa src/usr.sbin/ctladm/ctladm.8
as the backing store. as the backing store.
The size of the LUN will be derived from the size of the file. The size of the LUN will be derived from the size of the file.
.Pp .Pp
.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
.Pp .Pp
Create a LUN using the block backend, specify the file Create a LUN using the block backend, specify the file
.Pa src/usr.sbin/ctladm/ctladm.8 .Pa src/usr.sbin/ctladm/ctladm.8
as the backing store, and specify the as the backing store, and specify the
.Tn SCSI .Tn SCSI
VPD page 0x80 and 0x83 serial number VPD page 0x80 and 0x83 serial number
.Fl ( S ) .Fl ( S )
and device ID and device ID
.Fl ( d ) . .Fl ( d ) .
.Pp .Pp
.Dl ctladm remove -b block -l 12 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
.Pp .Pp
Use to specify generic options on ioctl frontend port, now it is
wblockUnsubmitted
Done
Inline Actions

s/Creates/Create/

wblock: s/Creates/Create/
only possible to set pp and/or vp port number.
.Pp
.Dl ctladm port -c -O pp=11 -O vp=12
.Pp
wblockUnsubmitted
Done
Inline Actions
Remove specified targ_port.
wblock: ```Remove specified targ_port.```
Remove specified targ_port.
.Pp
.Dl ctladm port -r -p 4
.Pp
.Pp
Remove LUN 12, which is handled by the block backend, from the system. Remove LUN 12, which is handled by the block backend, from the system.
.Pp .Pp
.Dl ctladm devlist .Dl ctladm remove -b block -l 12
.Pp .Pp
List configured LUNs in the system, along with their backend and serial List configured LUNs in the system, along with their backend and serial
number. number.
This works when the Front End Target Drivers are enabled or disabled. This works when the Front End Target Drivers are enabled or disabled.
.Pp .Pp
.Dl ctladm lunlist .Dl ctladm devlist
.Pp .Pp
List all LUNs in the system, along with their inquiry data and device type. List all LUNs in the system, along with their inquiry data and device type.
This only works when the FETDs are enabled, since the commands go through the This only works when the FETDs are enabled, since the commands go through the
ioctl port. ioctl port.
.Pp .Pp
.Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c .Dl ctladm lunlist
.Pp .Pp
Inject a medium error on LUN 6 for every read that covers the first 512 Inject a medium error on LUN 6 for every read that covers the first 512
blocks of the LUN. blocks of the LUN.
.Bd -literal -offset indent
ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
.Ed
.Pp .Pp
.Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
.Pp
Inject a custom error on LUN 6 for the next TEST UNIT READY command only. Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
0x04,0x02 ("Logical unit not ready, initializing command required"). 0x04,0x02 ("Logical unit not ready, initializing command required").
.Pp
.Bd -literal -offset indent
ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
.Ed
.Sh SEE ALSO .Sh SEE ALSO
.Xr cam 3 , .Xr cam 3 ,
.Xr cam_cdbparse 3 , .Xr cam_cdbparse 3 ,
.Xr cam 4 , .Xr cam 4 ,
.Xr ctl 4 , .Xr ctl 4 ,
.Xr xpt 4 , .Xr xpt 4 ,
.Xr camcontrol 8 , .Xr camcontrol 8 ,
.Xr ctld 8 , .Xr ctld 8 ,
.Xr ctlstat 8 .Xr ctlstat 8
.Sh HISTORY .Sh HISTORY
The The
.Nm .Nm
utility was originally written during the Winter/Spring of 2003 as an utility was originally written during the Winter/Spring of 2003 as an
interface to CTL. interface to CTL.
.Sh AUTHORS .Sh AUTHORS
.An Ken Merry Aq Mt ken@FreeBSD.org .An Ken Merry Aq Mt ken@FreeBSD.org