usr.sbin/ctld/ctld.8

   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 March 31, 2020
  30 .Dt CTLD 8
  31 .Os
  32 .Sh NAME
  33 .Nm ctld
  34 .Nd CAM Target Layer / iSCSI target daemon
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl d
  38 .Op Fl f Ar config-file
  39 .Op Fl u
  40 .Nm
  41 .Fl t
  42 .Op Fl f Ar config-file
  43 .Op Fl u
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 daemon is responsible for managing the CAM Target Layer configuration,
  48 accepting incoming iSCSI connections, performing authentication and
  49 passing connections to the kernel part of the native iSCSI target.
  50 .Pp
  51 Upon startup, the
  52 .Nm
  53 daemon parses the configuration file.
  54 If it encounters any errors,
  55 .Nm
  56 exits.
  57 It then compares the configuration with the kernel list of LUNs managed
  58 by previously running
  59 .Nm
  60 instances, removes LUNs no longer existing in the configuration file,
  61 and creates new LUNs as necessary.
  62 After that it listens for the incoming iSCSI connections, performs
  63 authentication, and, if successful, passes the connections to the kernel part
  64 of CTL iSCSI target,
  65 .Xr cfiscsi 4 ,
  66 which handles it from that point.
  67 .Pp
  68 When it receives a SIGHUP signal, the
  69 .Nm
  70 reloads its configuration and applies the changes to the kernel.
  71 Changes are applied in a way that avoids unnecessary disruptions;
  72 for example removing one LUN does not affect other LUNs.
  73 .Pp
  74 When exiting gracefully, the
  75 .Nm
  76 daemon removes LUNs it managed and forcibly disconnects all the clients.
  77 Otherwise - for example, when killed with SIGKILL - LUNs stay configured
  78 and clients remain connected.
  79 .Pp
  80 To perform administrative actions that apply to already connected
  81 sessions, such as forcing termination, use
  82 .Xr ctladm 8 .
  83 .Pp
  84 The following options are available:
  85 .Bl -tag -width ".Fl P Ar pidfile"
  86 .It Fl f Ar config-file
  87 Specifies the name of the configuration file.
  88 The default is
  89 .Pa /etc/ctl.conf .
  90 .It Fl d
  91 Debug mode.
  92 The daemon sends verbose debug output to standard error, and does not
  93 put itself in the background.
  94 The daemon will also not fork and will exit after processing one connection.
  95 This option is only intended for debugging the target.
  96 .It Fl t
  97 Test the configuration file for validity and exit.
  98 .It Fl u
  99 Use UCL configuration file format instead of the traditional non-UCL format.
 100 .El
 101 .Sh FILES
 102 .Bl -tag -width ".Pa /var/run/ctld.pid" -compact
 103 .It Pa /etc/ctl.conf
 104 The configuration file for
 105 .Nm .
 106 The file format and configuration options are described in
 107 .Xr ctl.conf 5 .
 108 .It Pa /var/run/ctld.pid
 109 The default location of the
 110 .Nm
 111 PID file.
 112 .El
 113 .Sh EXIT STATUS
 114 The
 115 .Nm
 116 utility exits 0 on success, and >0 if an error occurs.
 117 .Sh SEE ALSO
 118 .Xr cfiscsi 4 ,
 119 .Xr ctl 4 ,
 120 .Xr ctl.conf 5 ,
 121 .Xr ctladm 8 ,
 122 .Xr ctlstat 8
 123 .Sh HISTORY
 124 The
 125 .Nm
 126 command appeared in
 127 .Fx 10.0 .
 128 .Sh AUTHORS
 129 The
 130 .Nm
 131 was developed by
 132 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 133 under sponsorship from the FreeBSD Foundation.