xref: /freebsd/usr.bin/iscsictl/iscsictl.8 (revision 3332f1b444d4a73238e9f59cca27bfc95fe936bd)
1.\" Copyright (c) 2012 The FreeBSD Foundation
2.\"
3.\" This software was developed by Edward Tomasz Napierala under sponsorship
4.\" from the FreeBSD Foundation.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd December 27, 2018
30.Dt ISCSICTL 8
31.Os
32.Sh NAME
33.Nm iscsictl
34.Nd iSCSI initiator management utility
35.Sh SYNOPSIS
36.Nm
37.Fl A
38.Fl p Ar portal Fl t Ar target
39.Op Fl u Ar user Fl s Ar secret
40.Op Fl w Ar timeout
41.Op Fl r
42.Op Fl e Cm on Ns | Ns Cm off
43.Nm
44.Fl A
45.Fl d Ar discovery-host
46.Op Fl u Ar user Fl s Ar secret
47.Op Fl r
48.Op Fl e Cm on Ns | Ns Cm off
49.Nm
50.Fl A
51.Fl a Op Fl c Ar path
52.Nm
53.Fl A
54.Fl n Ar nickname Op Fl c Ar path
55.Nm
56.Fl M
57.Fl i Ar session-id
58.Op Fl p Ar portal
59.Op Fl t Ar target
60.Op Fl u Ar user
61.Op Fl s Ar secret
62.Op Fl e Cm on Ns | Ns Cm off
63.Nm
64.Fl M
65.Fl i Ar session-id
66.Op Fl n Ar nickname Op Fl c Ar path
67.Nm
68.Fl R
69.Op Fl p Ar portal
70.Op Fl t Ar target
71.Nm
72.Fl R
73.Fl a
74.Nm
75.Fl R
76.Fl n Ar nickname Op Fl c Ar path
77.Nm
78.Fl L
79.Op Fl v
80.Op Fl w Ar timeout
81.Sh DESCRIPTION
82The
83.Nm
84utility is used to configure the iSCSI initiator.
85.Pp
86The following options are available:
87.Bl -tag -width "-d discovery-host"
88.It Fl -libxo
89Generate output via
90.Xr libxo 3
91in a selection of different human and machine readable formats.
92See
93.Xr xo_parse_args 3
94for details on command line arguments.
95.It Fl A
96Add session.
97.It Fl M
98Modify session.
99.It Fl R
100Remove session.
101.It Fl L
102List sessions.
103.It Fl a
104When adding, add all sessions defined in the configuration file.
105When removing, remove all currently established sessions.
106.It Fl c Ar path
107Path to the configuration file.
108The default is
109.Pa /etc/iscsi.conf .
110.It Fl d Ar discovery-host
111Target host name or address used for SendTargets discovery.
112When used, it will add a temporary discovery session.
113After discovery is done, sessions will be added for each discovered target,
114and the temporary discovery session will be removed.
115.It Fl e Cm on Ns | Ns Cm off
116Enable or disable the session.
117This is ignored for discovery sessions, but gets passed down to normal
118sessions they add.
119.It Fl i Ar session-id
120Session ID, as displayed by
121.Nm
122.Fl v .
123.It Fl n Ar nickname
124The
125.Ar nickname
126of a session defined in the configuration file.
127.It Fl p Ar portal
128Target portal \(em host name or address \(em for statically defined targets.
129.It Fl r
130Use iSER (iSCSI over RDMA) instead of plain iSCSI over TCP/IP.
131.It Fl s Ar secret
132CHAP secret.
133.It Fl t Ar target
134Target name.
135.It Fl u Ar user
136CHAP login.
137.It Fl v
138Verbose mode.
139.It Fl w Ar timeout
140Instead of returning immediately, wait up to
141.Ar timeout
142seconds until all configured sessions are successfully established.
143.El
144.Pp
145Certain parameters are necessary when adding a session.
146One can specify these either via command line (using the
147.Fl t ,
148.Fl p ,
149.Fl u ,
150and
151.Fl s
152options), or configuration file (using the
153.Fl a
154or
155.Fl n
156options).
157Some functionality - for example mutual CHAP - is available only
158via configuration file.
159.Pp
160Since connecting to the target is performed in background, non-zero
161exit status does not mean that the session was successfully established.
162Use either
163.Nm Fl L
164to check the connection status, or the
165.Fl w
166flag to wait for session establishment.
167.Pp
168Note that in order for the iSCSI initiator to be able to connect to a target,
169the
170.Xr iscsid 8
171daemon must be running.
172.Sh FILES
173.Bl -tag -width ".Pa /etc/iscsi.conf" -compact
174.It Pa /etc/iscsi.conf
175iSCSI initiator configuration file.
176.El
177.Sh EXIT STATUS
178The
179.Nm
180utility exits 0 on success, and >0 if an error occurs.
181.Sh EXAMPLES
182Attach to target iqn.2012-06.com.example:target0, served by 192.168.1.1:
183.Dl Nm Fl A Fl t Ar iqn.2012-06.com.example:target0 Fl p Ar 192.168.1.1
184.Pp
185Perform discovery on 192.168.1.1, and add disabled sessions for each
186discovered target; use
187.Nm -M -e on
188to connect them:
189.Dl Nm Fl A Fl d Ar 192.168.1.1 Fl e Ar off
190.Pp
191Disconnect all iSCSI sessions:
192.Dl Nm Fl Ra
193.Sh SEE ALSO
194.Xr libxo 3 ,
195.Xr xo_parse_args 3 ,
196.Xr iscsi 4 ,
197.Xr iscsi.conf 5 ,
198.Xr iscsid 8
199.Sh HISTORY
200The
201.Nm
202command appeared in
203.Fx 10.0 .
204.Sh AUTHORS
205The
206.Nm
207utility was developed by
208.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
209under sponsorship from the FreeBSD Foundation.
210