forked from sahlberg/libiscsi
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
298 lines (226 loc) · 9.75 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
Libiscsi is a client-side library to implement the iSCSI protocol that can be used
to access the resources of an iSCSI target.
The library is fully asynchronous with regards to iSCSI commands and SCSI tasks,
but a synchronous layer is also provided for ease of use for simpler
applications.
The src directory contains a handful of useful iSCSI utilities such as logging in
to and enumerating all targets on a portal and all devices of a target.
The examples directory contains example implementation of how to access both the
synchronous and asynchronous APIs of libiscsi.
Libiscsi is a work in progress.
It aims to become a fully asynchronous library for iSCSI functionality, including
all features required to establish and maintain an iSCSI session, as well as a
low-level SCSI library to create SCSI CDBs and parse/unmarshall data-in structures.
Installation
============
./autogen.sh
./configure
make
sudo make install
Build RPM
=========
To build RPMs run the following script from the libiscsi root directory
./packaging/RPM/makerpms.sh
iSCSI URL Format
================
iSCSI devices are specified by a URL format of the following form :
iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn>/<lun>[?<argument>[&<argument>]*]
Arguments:
Username and password for bidirectional CHAP authentication:
target_user=<account>
target_password=<password>
Example:
iscsi://server/iqn.ronnie.test/1
CHAP Authentication
===================
CHAP authentication can be specified two ways. Either via the URL itself
or through environment variables.
Note that when setting it via the URL, be careful so that username/password
will not be visible in logfiles or the process list.
URL
---
CHAP authentication via URL is specified by providing <username>%<password>@
in the server part of the URL:
Example:
iscsi://ronnie%password@server/iqn.ronnie.test/1
Environment variables
---------------------
Setting the CHAP authentication via environment variables:
LIBISCSI_CHAP_USERNAME=ronnie
LIBISCSI_CHAP_PASSWORD=password
Example:
LIBISCSI_CHAP_PASSWORD=password iscsi-inq iscsi://[email protected]/iqn.ronnie.test/1
Bidirectional CHAP Authentication
=================================
Bidirectional CHAP is when you not only authenticate the initiator to the target
but also authenticate the target back to the initiator.
This is only available if you also first specify normal authentication as per
the previous section.
Bidirectional CHAP can be set either via URL arguments or via environment
variables. If specifying it via URL arguments, be careful so that you do
not leak the username/password via logfiles or the process list or similar.
URL
---
URL arguments contain the '&' character so make sure to escape them properly
if you pass them in via a commandline.
Example:
iscsi://127.0.0.1/iqn.ronnie.test/1?target_user=target\&target_password=target
Environment variables
---------------------
Setting the CHAP authentication via environment variables:
LIBISCSI_CHAP_TARGET_USERNAME=target
LIBISCSI_CHAP_TARGET_PASSWORD=password
IPv6 support
============
Libiscsi supports IPv6, either as names resolving into IPv6 addresses or when
IPv6 addresses are explicitely set in the URL.
When specifying IPv6 addresses in the URL, they have to be specified in
[...] bracket form.
Example:
iscsi://[fec0:2727::3]:3260/iqn.ronnie.test/1
Header Digest
=============
Libiscsi supports HeaderDigest.
By default, libiscsi will offer None,CRC32C and let the target pick whether
Header digest is to be used or not.
This can be overridden by an application by calling iscsi_set_header_digest()
if the application wants to force a specific setting.
Patches
=======
The patches subdirectory contains patches to make some external packages
iSCSI-aware and make them use libiscsi.
Currently we have SG3-UTILS and MTX.
Patches for other packages would be welcome.
ISCSI-TEST-CU
=============
iscsi-test-cu is a CUnit based test tool for scsi and iscsi.
iscsi-test-cu depends on the CUnit library and will only build if libcunit can be
found during configure.
The configure script will check if a suitable libcunit is available and only
build the test tool if it can find libcunit.
This test is done toward the end of the configure phase and should result
in a line similar to :
checking whether libcunit is available... yes
Test family/suite/test
----------------------
Tests are divided up in families, suites and tests and are specified as
--test=<family>.<suite>.<test>
A <family> is a logical collection of test suites to cover a broad set
of functionality. Example families are 'SCSI' for performing all tests for
SCSI commands and 'iSCSI' that contain tests for the iSCSI layer.
To run all tests in the SCSI family you can just specify
--test=SCSI or --test=SCSI.*.*
The next layer of tests are the suites. Within a family there are a collection
of suites that perform test to cover a specific area of functionality.
For example, to run all SCSI tests that cover the Read10 opcode you would
specify it as
--test=SCSI.Read10 or --test=SCSI.Read10.*
Finally at the lowest level you have the individual tests. These tests perform
specific topic in a suite.
For example, we have tests for the Read10 opcode that verifies that the target
implements the DPO/FUA flags properly.
To run those tests you would specify
--test=SCSI.Read10.DpoFua
Test discovery
--------------
To discover which tests exist you can use the command
iscsi-test-cu --list
Examples
--------
Run the DpoFua test for Read10
iscsi-test-cu --test=SCSI.Read10.DpoFua iscsi://127.0.0.1/iqn.example.test/1
Run all Read10 tests
iscsi-test-cu --test=SCSI.Read10 iscsi://127.0.0.1/iqn.example.test/1
Run all SCSI tests for all opcodes
iscsi-test-cu --test=SCSI iscsi://127.0.0.1/iqn.example.test/1
Initiator names used by the test suite
--------------------------------------
Most tests only require a single login to the target, but some tests,
for example the it nexus loss tests may need to login two separate sessions.
By default the initiator names use for the logins will be
"iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-test";
for the primary connection for all tests, and
"iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-test-2"
for the secondary connection for the test that needs two sessions.
These names can be controlled by using the arguments
--initiator-name and --initiator-name-2
The tests are all self-documented to describe what they test and how they test.
Use -V with a test to print the documentation for a test.
XLM/JUNIT
=========
iscsi-test-cu can produce machine-readable test results for consumption by your
CI server. Use the --xml option with any test suite(s), and a file called
CUnitAutomated-Results.xml will be written to your current working directory.
These results can be converted to JUnit format using this script:
http://git.cyrusimap.org/cyrus-imapd/plain/cunit/cunit-to-junit.pl
See also:
CUnit-List.xsl
--------------
https://code.google.com/p/warc-tools/source/browse/trunk/utest/outputs/CUnit-List.xsl
CUnit-Run.xsl
-------------
https://code.google.com/p/mdflib/source/browse/trunk/cunit/CUnit-Run.xsl
Linux SG_IO devices
-------------------
When used on Linux, the test tool also supports talking directly to local SG_IO
devices. Accessing SG_IO devices often require that you are root:
sudo iscsi-test-cu --test LINUX.Read10.Simple /dev/sg1
Unit Tests
----------
The tests directory contains test scripts and programs to verify the
functionality of libiscsi itself. These tests require that you have STGT
version 1.0.58 or later installed to use as a taget to test against.
To run the tests:
cd tests
make test
LD_PRELOAD FUN
==============
There is a small LD_PRELOAD hack in the src directory that intercepts a handful
of system calls and converts iSCSI URLs to look and behave as if they are normal
read-only files.
This allows using standard UNIX tools to become iSCSI-aware with no
modifications.
For example:
The stat command: this shows the size of the iSCSI LUN as if it was a normal file:
$ LD_PRELOAD=ld_iscsi.so stat iscsi://127.0.0.1:3262/iqn.ronnie.test/2
File: `iscsi://127.0.0.1:3262/iqn.ronnie.test/2'
Size: 3431540736 Blocks: 0 IO Block: 0 regular file
Device: 0h/0d Inode: 0 Links: 0
Access: (0444/-r--r--r--) Uid: ( 0/ root) Gid: ( 0/ root)
Access: 1970-01-01 10:00:00.000000000 +1000
Modify: 1970-01-01 10:00:00.000000000 +1000
Change: 1970-01-01 10:00:00.000000000 +1000
The cat command, which allows you to read/dump a iSCSI LUN to a file :
$ LD_PRELOAD=ld_iscsi.so cat iscsi://127.0.0.1:3262/iqn.ronnie.test/2 >copy_of_iscsi_lun
Or using dd even :
$ LD_PRELOAD=ld_iscsi.so dd if=iscsi://127.0.0.1:3262/iqn.ronnie.test/2 of=copy_of_LUN bs=10M count=1
The LD_PRELOAD hack is incomplete and needs more functions to be intercepted
before becoming fully functional. Patches welcome!
For now, it is sufficiently complete for trivial commands like stat and cat.
You probably need to implement at least lseek, pread, pwrite before it becomes
really useful.
SUPPORTED PLATFORMS
===================
libiscsi is pure POSIX and should with some tweaks run on any host that
provides a POSIX-like environment.
Libiscsi has been tested on:
* Linux (32 and 64 bit)
* Cygwin
* FreeBSD
* Windows (Win7-VisualStudio10)
* OpenSolaris
* Solaris 11 : Use "gmake" to build.
* OS X
RELEASE TARBALLS
================
Release tarballs are available at https://sites.google.com/site/libiscsitarballs/libiscsitarballs/
CONTRIBUTING
============
If you want to contribute, please do.
For sending me patches you can either do that by sending a pull request to my
github repo or you can send them in an email directly to me at
MAILINGLIST
===========
A libiscsi mailing list is available at http://groups.google.com/group/libiscsi
Announcements of new versions of libiscsi will be posted to this list.