usr.sbin/ctld/ctld.8

   1 .\" Copyright (c) 2012 The FreeBSD Foundation
   2 .\" All rights reserved.
   3 .\"
   4 .\" This software was developed by Edward Tomasz Napierala under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd September 20, 2012
  31 .Dt CTLD 8
  32 .Os
  33 .Sh NAME
  34 .Nm ctld
  35 .Nd CAM Target Layer / iSCSI target daemon
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl d
  39 .Op Fl f Ar config-file
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 daemon is responsible for managing the CAM Target Layer configuration,
  44 accepting incoming iSCSI connections, performing authentication and
  45 passing connections to the kernel part of the native iSCSI target.
  46 .Pp
  47 Upon startup, the
  48 .Nm
  49 daemon parses the configuration file and exits, if it encounters any errors.
  50 Then it compares the configuration with the kernel list of LUNs managed
  51 by previously running
  52 .Nm
  53 instances, removes LUNs no longer existing in the configuration file,
  54 and creates new LUNs as neccessary.
  55 After that it listens for the incoming iSCSI connections, performs
  56 authentication, and, if successful, passes the connections to the kernel part
  57 of CTL iSCSI target, which handles it from that point.
  58 .Pp
  59 When it receives a SIGHUP signal, the
  60 .Nm
  61 reloads its configuration and applies the changes to the kernel.
  62 Changes are applied in a way that avoids unneccessary disruptions;
  63 for example removing one LUN does not affect other LUNs.
  64 .Pp
  65 When exiting gracefully, the
  66 .Nm
  67 daemon removes LUNs it managed and forcibly disconnects all the clients.
  68 Otherwise - e.g. when killed with SIGKILL - LUNs stay configured
  69 and clients remain connected.
  70 .Pp
  71 To perform administrative actions that apply to already connected
  72 sessions, such as forcing termination, use
  73 .Xr ctladm 8 .
  74 .Pp
  75 The following options are available:
  76 .Bl -tag -width ".Fl P Ar pidfile"
  77 .It Fl f Ar config-file
  78 Specifies the name of the configuration file.
  79 The default is
  80 .Pa /etc/ctl.conf .
  81 .It Fl d
  82 Debug mode.
  83 The server sends verbose debug output to standard error, and does not
  84 put itself in the background.
  85 The server will also not fork and will exit after processing one connection.
  86 This option is only intended for debugging the target.
  87 .El
  88 .Sh FILES
  89 .Bl -tag -width ".Pa /var/run/ctld.pid" -compact
  90 .It Pa /etc/ctl.conf
  91 The configuration file for
  92 .Nm .
  93 The file format and configuration options are described in
  94 .Xr ctl.conf 5 .
  95 .It Pa /var/run/ctld.pid
  96 The default location of the
  97 .Nm
  98 PID file.
  99 .El
 100 .Sh EXIT STATUS
 101 The
 102 .Nm
 103 utility exits 0 on success, and >0 if an error occurs.
 104 .Sh SEE ALSO
 105 .Xr ctl 4 ,
 106 .Xr ctl.conf 5 ,
 107 .Xr ctladm 8
 108 .Sh AUTHORS
 109 The
 110 .Nm
 111 was developed by
 112 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
 113 under sponsorship from the FreeBSD Foundation.