From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-11.8 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id F2683C433E0 for ; Sat, 6 Mar 2021 00:53:39 +0000 (UTC) Received: from desiato.infradead.org (desiato.infradead.org [90.155.92.199]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 6123D65077 for ; Sat, 6 Mar 2021 00:53:39 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6123D65077 Authentication-Results: mail.kernel.org; dmarc=fail (p=quarantine dis=none) header.from=suse.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-nvme-bounces+linux-nvme=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=desiato.20200630; h=Sender:Content-Transfer-Encoding :Content-Type:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To:Message-Id:Date: Subject:Cc:To:From:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=ZxAeinuo6osnoYEdZ8zbSi7CCR8jeR10tfakuU8yh6k=; b=rLFFrma4C5HA2e6lQIoy24wUS bx3g8ZNFgErAxgxO9c/5833VYqSmmsEDjopE+ofLWL7cbky6XCoy3sF1E5iX9onxGyCAuUXS2Ej0V irBMg+sDE6OghDAIZSGcW88xSl3lMGLxzO6vVneYQS03sIFAh3tmT+j97SsmfChDHU6swS8+yFLed 0zWgftcOVHa/5/SGfDIuSgVcJ0shCZCJjh/KNZRqw5j8528naz94Nod41duNH9LHFz1bbqEcn1oWp 21Vn9KC6/az2k5zJpLCUdHWj3wrsuNXxDRSH82lp9j76R7YmUoiZXbg792mLaVbTg2USXK3IDmNhm 6bBZyXagw==; Received: from localhost ([::1] helo=desiato.infradead.org) by desiato.infradead.org with esmtp (Exim 4.94 #2 (Red Hat Linux)) id 1lILC3-00HauM-O9; Sat, 06 Mar 2021 00:53:20 +0000 Received: from mx2.suse.de ([195.135.220.15]) by desiato.infradead.org with esmtps (Exim 4.94 #2 (Red Hat Linux)) id 1lIKwf-00HVkG-Ml for linux-nvme@lists.infradead.org; Sat, 06 Mar 2021 00:37:31 +0000 X-Virus-Scanned: by amavisd-new at test-mx.suse.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=susede1; t=1614991041; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Wq27Nn+ryzchd0rYU8bPsS5Gxwqk4hr8+XxP7NqMPFA=; b=LHtv7zaa4CeVMsxrnlCK+bBm/sCOUQgWYVCCHYZmdyKuHmoZpj4rYGTJlsbqf3qVxAxGQF tMIG2qxRg9hJ/Ly+L3cKIaK9XvLbQBTmn7p6vorGFpAqhFqTv5ZE7lNDYC1mE73KrJ1+mS AgjDwVmxn4yLh8HmAaHXnYldem8maf8= Received: from relay2.suse.de (unknown [195.135.221.27]) by mx2.suse.de (Postfix) with ESMTP id 01C5FAF5C; Sat, 6 Mar 2021 00:37:21 +0000 (UTC) From: mwilck@suse.com To: Sagi Grimberg , Hannes Reinecke , Keith Busch Cc: Chaitanya Kulkarni , linux-nvme@lists.infradead.org, Enzo Matsumiya , Martin Wilck Subject: [PATCH v2 16/16] nvme-monitor(1): add man page for nvme-monitor Date: Sat, 6 Mar 2021 01:36:59 +0100 Message-Id: <20210306003659.21207-17-mwilck@suse.com> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20210306003659.21207-1-mwilck@suse.com> References: <20210306003659.21207-1-mwilck@suse.com> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210306_003727_118091_99AC83FC X-CRM114-Status: GOOD ( 16.75 ) X-BeenThere: linux-nvme@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "Linux-nvme" Errors-To: linux-nvme-bounces+linux-nvme=archiver.kernel.org@lists.infradead.org From: Martin Wilck Add documentation for the nvme-monitor command. --- Documentation/cmds-main.txt | 4 + Documentation/nvme-monitor.1 | 180 ++++++ Documentation/nvme-monitor.html | 1018 +++++++++++++++++++++++++++++++ Documentation/nvme-monitor.txt | 144 +++++ 4 files changed, 1346 insertions(+) create mode 100644 Documentation/nvme-monitor.1 create mode 100644 Documentation/nvme-monitor.html create mode 100644 Documentation/nvme-monitor.txt diff --git a/Documentation/cmds-main.txt b/Documentation/cmds-main.txt index 46df03d..d058a54 100644 --- a/Documentation/cmds-main.txt +++ b/Documentation/cmds-main.txt @@ -168,3 +168,7 @@ linknvme:nvme-disconnect-all[1]:: linknvme:nvme-get-property[1]:: Reads and shows NVMe-over-Fabrics controller property + +linknvme:nvme-monitor[1]:: + Monitor Discovery events and Discover and Connect automatically + diff --git a/Documentation/nvme-monitor.1 b/Documentation/nvme-monitor.1 new file mode 100644 index 0000000..c87988e --- /dev/null +++ b/Documentation/nvme-monitor.1 @@ -0,0 +1,180 @@ +'\" t +.\" Title: nvme-monitor +.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 02/25/2021 +.\" Manual: NVMe Manual +.\" Source: NVMe +.\" Language: English +.\" +.TH "NVME\-MONITOR" "1" "02/25/2021" "NVMe" "NVMe Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +nvme-monitor \- Monitor Discovery events and Discover and Connect automatically +.SH "SYNOPSIS" +.sp +.nf +\fInvme discover\fR + [\-\-no\-auto | \-N] + [\-\-hostnqn= | \-q ] + [\-\-hostid= | \-I ] + [\-\-keep\-alive\-tmo=<#> | \-k <#>] + [\-\-reconnect\-delay=<#> | \-c <#>] + [\-\-ctrl\-loss\-tmo=<#> | \-l <#>] + [\-\-hdr\-digest | \-g] + [\-\-data\-digest | \-G] + [\-\-nr\-io\-queues=<#> | \-i <#>] + [\-\-nr\-write\-queues=<#> | \-W <#>] + [\-\-nr\-poll\-queues=<#> | \-P <#>] + [\-\-queue\-size=<#> | \-Q <#>] + [\-\-matching | \-m] + [\-\-persistent | \-p] + [\-\-silent | \-S] + [\-\-verbose | \-v] + [\-\-debug | \-D] + [\-\-timestamps | \-t] +.fi +.SH "DESCRIPTION" +.sp +Listen to Discovery events (Asynchronous Event Notifications, AENs) on NVMe\-over\-Fabrics (NVMeoF) Discovery Controllers and for other events related to NVMeoF Discovery, and optionally connect to newly discovered controllers\&. +.sp +If no parameters are given, then \fInvme monitor\fR listens to Discovery\-related udev events (uevents)\&. If an event is received, it connects to the Discovery Controller and performs the equivalent of an \fInvme connect\-all\fR on the associated transport address\&. When run through a systemd service in rhis mode, the monitor can be used as an alternative to the udev\-rule based auto\-activation of NVMeoF connections\&. If this is done, it is recommended to deactivate the udev rule\-based autoconnection mechanism, e\&.g\&. by creating a symlink /run/udev/rules\&.d/70\-nvmf\-autoconnect\&.rules to /dev/null\&. Otherwise both mechanisms will run discovery in parallel, which causes unnecessary system activity spurious error messages\&. +.sp +Currently, the following event types are supported: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"Discovery Log Page Change" Asynchronous Event Notifications (AENs) delivered via persistent connections to NVMeoF discovery controllers connected to the discovery service (nqn\&.2014\-08\&.org\&.nvmexpress\&.discovery)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +FC\-NVMe auto\-connect uevents sent when the FibreChannel transport discovers N_Ports offering NVMe services\&. +.RE +.sp +See the documentation for the nvme\-connect\-all(1) and nvme\-discover(1) commands for further background\&. +.SH "OPTIONS" +.PP +\-N, \-\-no\-connect +.RS 4 +If this option is given, +\fInvme monitor\fR +will not attempt to connect to newly discovered controllers\&. Instead, information about found discovery log entries will be printed to stdout (in other words, instead of +\fInvme connect\-all\fR, the monitor only executes +\fInvme discover\fR +for detected discovery controllers)\&. +.RE +.PP +\-C, \-\-cleanup +.RS 4 +Disconnect discovery controllers when the program exits\&. This affects only discovery controller connections created while the program was running\&. +.RE +.PP +\-q , \-\-hostnqn=, \-I , \-\-hostid=, \-k <#>, \-\-keep\-alive\-tmo=<#>, \-c <#>, \-\-reconnect\-delay=<#>, \-l <#>, \-\-ctrl\-loss\-tmo=<#>, \-g, \-\-hdr\-digest, \-G, \-\-data\-digest, \-i <#>, \-\-nr\-io\-queues=<#>, \-W <#>, \-\-nr\-write\-queues=<#>, \-P <#>, \-\-nr\-poll\-queues=<#>, \-Q <#>, \-\-queue\-size=<#>, \-m, \-\-matching +.RS 4 +These options have the same meaning as for +\fInvme connect\-all\fR\&. See the man page nvme\-connect\-all(1) for details\&. +.RE +.PP +\-S, \-\-silent +.RS 4 +Only print warnings and severe error messages\&. Do not log discoveries and newly created controllers\&. +.RE +.PP +\-v, \-\-verbose +.RS 4 +Log informational messages\&. This option overrides +\fI\-\-silent\fR\&. +.RE +.PP +\-D, \-\-debug +.RS 4 +Log informational and debug messages\&. This option overrieds +\fI\-\-silent\fR +and +\fI\-\-verbose\fR\&. +.RE +.PP +\-t, \-\-timestamps +.RS 4 +Add timestamps to log messages\&. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Listen to FC\-NVME events and AENs, creating persistent Discovery Controllers on the way, and automatically connect to all discovered controllers: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# nvme monitor +.fi +.if n \{\ +.RE +.\} +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Like the above, but print more log messages, remove created discovery controller connections on exit, and use a non\-standard host NQN: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# nvme monitor \-\-verbose \-\-cleanup \-\-hostqn=host1\-rogue\-nqn +.fi +.if n \{\ +.RE +.\} +.RE +.SH "SEE ALSO" +.sp +nvme\-discover(1) nvme\-connect\-all(1) +.SH "NVME" +.sp +Part of the nvme\-user suite diff --git a/Documentation/nvme-monitor.html b/Documentation/nvme-monitor.html new file mode 100644 index 0000000..bcc8f93 --- /dev/null +++ b/Documentation/nvme-monitor.html @@ -0,0 +1,1018 @@ + + + + + + +nvme-monitor(1) + + + + + +
+
+

SYNOPSIS

+
+
+
nvme discover
+                [--no-auto                | -N]
+                [--hostnqn=<hostnqn>      | -q <hostnqn>]
+                [--hostid=<hostid>        | -I <hostid>]
+                [--keep-alive-tmo=<#>     | -k <#>]
+                [--reconnect-delay=<#>    | -c <#>]
+                [--ctrl-loss-tmo=<#>      | -l <#>]
+                [--hdr-digest             | -g]
+                [--data-digest            | -G]
+                [--nr-io-queues=<#>       | -i <#>]
+                [--nr-write-queues=<#>    | -W <#>]
+                [--nr-poll-queues=<#>     | -P <#>]
+                [--queue-size=<#>         | -Q <#>]
+                [--matching               | -m]
+                [--persistent             | -p]
+                [--silent                 | -S]
+                [--verbose                | -v]
+                [--debug                  | -D]
+                [--timestamps             | -t]
+
+
+
+
+
+

DESCRIPTION

+
+

Listen to Discovery events (Asynchronous Event Notifications, AENs) on +NVMe-over-Fabrics (NVMeoF) Discovery Controllers and for other events related +to NVMeoF Discovery, and optionally connect to newly discovered controllers.

+

If no parameters are given, then nvme monitor listens to Discovery-related +udev events (uevents). If an event is received, it connects to the Discovery +Controller and performs the equivalent of an nvme connect-all on the +associated transport address. When run through a systemd service in rhis +mode, the monitor can be used as an alternative to the udev-rule based +auto-activation of NVMeoF connections. If this is done, it is recommended +to deactivate the udev rule-based autoconnection mechanism, e.g. by creating +a symlink /run/udev/rules.d/70-nvmf-autoconnect.rules to /dev/null. +Otherwise both mechanisms will run discovery in parallel, which causes +unnecessary system activity spurious error messages.

+

Currently, the following event types are supported:

+
    +
  • +

    +"Discovery Log Page Change" Asynchronous Event Notifications (AENs) + delivered via persistent connections to NVMeoF discovery controllers + connected to the discovery service (nqn.2014-08.org.nvmexpress.discovery). +

    +
    • +
  • +

    +FC-NVMe auto-connect uevents sent when the FibreChannel transport discovers + N_Ports offering NVMe services. +

    +
    • +
+

See the documentation for the nvme-connect-all(1) and nvme-discover(1) +commands for further background.

+
+
+
+

OPTIONS

+
+
+
+-N +
+
+--no-connect +
+
+

+ If this option is given, nvme monitor will not attempt to connect to + newly discovered controllers. Instead, information about found + discovery log entries will be printed to stdout (in other words, instead of + nvme connect-all, the monitor only executes nvme discover for + detected discovery controllers). +

+
+
+-C +
+
+--cleanup +
+
+

+ Disconnect discovery controllers when the program exits. This affects + only discovery controller connections created while the program was running. +

+
+
+-q <hostnqn> +
+
+--hostnqn=<hostnqn> +
+
+-I <hostid> +
+
+--hostid=<hostid> +
+
+-k <#> +
+
+--keep-alive-tmo=<#> +
+
+-c <#> +
+
+--reconnect-delay=<#> +
+
+-l <#> +
+
+--ctrl-loss-tmo=<#> +
+
+-g +
+
+--hdr-digest +
+
+-G +
+
+--data-digest +
+
+-i <#> +
+
+--nr-io-queues=<#> +
+
+-W <#> +
+
+--nr-write-queues=<#> +
+
+-P <#> +
+
+--nr-poll-queues=<#> +
+
+-Q <#> +
+
+--queue-size=<#> +
+
+-m +
+
+--matching +
+
+

+ These options have the same meaning as for nvme connect-all. See the + man page nvme-connect-all(1) for details. +

+
+
+-S +
+
+--silent +
+
+

+ Only print warnings and severe error messages. Do not log discoveries + and newly created controllers. +

+
+
+-v +
+
+--verbose +
+
+

+ Log informational messages. This option overrides --silent. +

+
+
+-D +
+
+--debug +
+
+

+ Log informational and debug messages. This option overrieds --silent + and --verbose. +

+
+
+-t +
+
+--timestamps +
+
+

+ Add timestamps to log messages. +

+
+
+
+
+
+

EXAMPLES

+
+
    +
  • +

    +Listen to FC-NVME events and AENs, creating persistent Discovery Controllers +on the way, and automatically connect to all discovered controllers: +

    +
    +
    +
    # nvme monitor
    +
    +
    • +
  • +

    +Like the above, but print more log messages, remove created discovery controller +connections on exit, and use a non-standard host NQN: +

    +
    +
    +
    # nvme monitor --verbose --cleanup --hostqn=host1-rogue-nqn
    +
    +
    • +
+
+
+
+

SEE ALSO

+
+

nvme-discover(1) +nvme-connect-all(1)

+
+
+
+

NVME

+
+

Part of the nvme-user suite

+
+
+
+
+ + + diff --git a/Documentation/nvme-monitor.txt b/Documentation/nvme-monitor.txt new file mode 100644 index 0000000..79f9c03 --- /dev/null +++ b/Documentation/nvme-monitor.txt @@ -0,0 +1,144 @@ +nvme-monitor(1) +=============== + +NAME +---- +nvme-monitor - Monitor Discovery events and Discover and Connect automatically + +SYNOPSIS +-------- +[verse] +'nvme discover' + [--no-auto | -N] + [--hostnqn= | -q ] + [--hostid= | -I ] + [--keep-alive-tmo=<#> | -k <#>] + [--reconnect-delay=<#> | -c <#>] + [--ctrl-loss-tmo=<#> | -l <#>] + [--hdr-digest | -g] + [--data-digest | -G] + [--nr-io-queues=<#> | -i <#>] + [--nr-write-queues=<#> | -W <#>] + [--nr-poll-queues=<#> | -P <#>] + [--queue-size=<#> | -Q <#>] + [--matching | -m] + [--persistent | -p] + [--silent | -S] + [--verbose | -v] + [--debug | -D] + [--timestamps | -t] + +DESCRIPTION +----------- +Listen to Discovery events (Asynchronous Event Notifications, AENs) on +NVMe-over-Fabrics (NVMeoF) Discovery Controllers and for other events related +to NVMeoF Discovery, and optionally connect to newly discovered controllers. + +If no parameters are given, then 'nvme monitor' listens to Discovery-related +udev events (uevents). If an event is received, it connects to the Discovery +Controller and performs the equivalent of an 'nvme connect-all' on the +associated transport address. When run through a systemd service in this +mode, the monitor can be used as an alternative to the udev-rule based +auto-activation of NVMeoF connections. If this is done, it is recommended +to deactivate the udev rule-based autoconnection mechanism, e.g. by creating +a symlink `/run/udev/rules.d/70-nvmf-autoconnect.rules` to `/dev/null`. +Otherwise both mechanisms will run discovery in parallel, which causes +unnecessary system activity and spurious error messages. + +Currently, the following event types are supported: + +- "Discovery Log Page Change" Asynchronous Event Notifications (AENs) + delivered via persistent connections to NVMeoF discovery controllers + connected to the discovery service (`nqn.2014-08.org.nvmexpress.discovery`). + +- FC-NVMe auto-connect uevents sent when the FibreChannel transport discovers + N_Ports offering NVMe services. + +See the documentation for the nvme-connect-all(1) and nvme-discover(1) +commands for further background. + +OPTIONS +------- + +-N:: +--no-connect:: + If this option is given, 'nvme monitor' will not attempt to connect to + newly discovered controllers. Instead, information about found + discovery log entries will be printed to stdout (in other words, instead of + 'nvme connect-all', the monitor only executes 'nvme discover' for + detected discovery controllers). + +-C:: +--cleanup:: + Disconnect discovery controllers when the program exits. This affects + only discovery controller connections created while the program was running. + +-q :: +--hostnqn=:: +-I :: +--hostid=:: +-k <#>:: +--keep-alive-tmo=<#>:: +-c <#>:: +--reconnect-delay=<#>:: +-l <#>:: +--ctrl-loss-tmo=<#>:: +-g:: +--hdr-digest:: +-G:: +--data-digest:: +-i <#>:: +--nr-io-queues=<#>:: +-W <#>:: +--nr-write-queues=<#>:: +-P <#>:: +--nr-poll-queues=<#>:: +-Q <#>:: +--queue-size=<#>:: +-m:: +--matching:: + These options have the same meaning as for 'nvme connect-all'. See the + man page nvme-connect-all(1) for details. + +-S:: +--silent:: + Only print warnings and severe error messages. Do not log discoveries + and newly created controllers. + +-v:: +--verbose:: + Log informational messages. This option overrides '--silent'. + +-D:: +--debug:: + Log informational and debug messages. This option overrieds '--silent' + and '--verbose'. + +-t:: +--timestamps:: + Add timestamps to log messages. + +EXAMPLES +-------- +* Listen to FC-NVME events and AENs, creating persistent Discovery Controllers +on the way, and automatically connect to all discovered controllers: ++ +------------- +# nvme monitor +------------- ++ +* Like the above, but print more log messages, remove created discovery controller +connections on exit, and use a non-standard host NQN: ++ +------------ +# nvme monitor --verbose --cleanup --hostqn=host1-rogue-nqn +------------ + +SEE ALSO +-------- +nvme-discover(1) +nvme-connect-all(1) + +NVME +---- +Part of the nvme-user suite -- 2.29.2 _______________________________________________ Linux-nvme mailing list Linux-nvme@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-nvme