Independent Submission M. Stubbig
Request for Comments: 8522 Independent
Category: Informational February 2019
ISSN: 2070-1721
Independent Submission M. Stubbig
Request for Comments: 8522 Independent
Category: Informational February 2019
ISSN: 2070-1721
Looking Glass Command Set
观察镜命令集
Abstract
摘要
This document introduces a command set standard to the web-based "Network Looking Glass" software. Its purpose is to provide application programmers uniform access to the Looking Glass service and to analyze a standardized response.
本文档介绍了基于web的“网络窥镜”软件的命令集标准。它的目的是为应用程序程序员提供对Looking Glass服务的统一访问，并分析标准化响应。
The interface is supposed to provide the same level of information as web-based interfaces, but in a computer-readable format.
该接口应提供与基于web的接口相同级别的信息，但应采用计算机可读的格式。
Status of This Memo
关于下段备忘
This document is not an Internet Standards Track specification; it is published for informational purposes.
本文件不是互联网标准跟踪规范；它是为了提供信息而发布的。
This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not candidates for any level of Internet Standard; see Section 2 of RFC 7841.
这是对RFC系列的贡献，独立于任何其他RFC流。RFC编辑器已选择自行发布此文档，并且未声明其对实现或部署的价值。RFC编辑批准发布的文件不适用于任何级别的互联网标准；见RFC 7841第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8522.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问https://www.rfc-editor.org/info/rfc8522.
Copyright Notice
版权公告
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
版权（c）2019 IETF信托基金和被确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(https://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。
Table of Contents
目录
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 3
1.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 4
2.2. Query Parameters . . . . . . . . . . . . . . . . . . . . 5
2.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1. Diagnostic Commands . . . . . . . . . . . . . . . . . . . 9
3.2. Informational Commands . . . . . . . . . . . . . . . . . 10
3.3. Organizational Commands . . . . . . . . . . . . . . . . . 14
3.4. Extensible Commands . . . . . . . . . . . . . . . . . . . 16
4. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . 16
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
5.1. Well-Known URIs Registry . . . . . . . . . . . . . . . . 17
6. Security Considerations . . . . . . . . . . . . . . . . . . . 17
6.1. Abuse Potential . . . . . . . . . . . . . . . . . . . . . 17
6.2. Authentication . . . . . . . . . . . . . . . . . . . . . 17
6.3. Minimal Information . . . . . . . . . . . . . . . . . . . 17
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.1. Normative References . . . . . . . . . . . . . . . . . . 18
7.2. Informative References . . . . . . . . . . . . . . . . . 19
Appendix A. JSend . . . . . . . . . . . . . . . . . . . . . . . 20
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 3
1.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 4
2.2. Query Parameters . . . . . . . . . . . . . . . . . . . . 5
2.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1. Diagnostic Commands . . . . . . . . . . . . . . . . . . . 9
3.2. Informational Commands . . . . . . . . . . . . . . . . . 10
3.3. Organizational Commands . . . . . . . . . . . . . . . . . 14
3.4. Extensible Commands . . . . . . . . . . . . . . . . . . . 16
4. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . 16
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
5.1. Well-Known URIs Registry . . . . . . . . . . . . . . . . 17
6. Security Considerations . . . . . . . . . . . . . . . . . . . 17
6.1. Abuse Potential . . . . . . . . . . . . . . . . . . . . . 17
6.2. Authentication . . . . . . . . . . . . . . . . . . . . . 17
6.3. Minimal Information . . . . . . . . . . . . . . . . . . . 17
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.1. Normative References . . . . . . . . . . . . . . . . . . 18
7.2. Informative References . . . . . . . . . . . . . . . . . 19
Appendix A. JSend . . . . . . . . . . . . . . . . . . . . . . . 20
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
Many Internet service providers (ISPs) and Internet exchange points (IXPs) offer a complimentary web-based service to their customers and the general public that gives insights to the backbone routing table, BGP neighbor information, or offered routes. This service is known as a "Network Looking Glass". Because they utilize a web-based interface, it is hard to automate access to the services and make that automation transferable between different service implementations.
许多互联网服务提供商（ISP）和互联网交换点（IXP）向其客户和普通公众提供免费的基于网络的服务，以了解主干路由表、BGP邻居信息或提供的路由。这项服务被称为“网络窥镜”。因为它们使用基于web的界面，所以很难自动化对服务的访问并使自动化在不同的服务实现之间转移。
This document describes a common command set to provide application programmers uniform access to Looking Glass services.
本文档描述了一个通用命令集，用于为应用程序程序员提供对Looking Glass服务的统一访问。
The commands are intended to provide the same level of information as available via web-based interfaces, but to do so in a computer-readable format. The intention is that multiple implementers of Looking Glass services can provide access through these commands so that an application can make use of the different implementations.
这些命令旨在提供与通过基于web的界面提供的信息相同级别的信息，但以计算机可读的格式提供。其目的是多个lookglass服务的实现者可以通过这些命令提供访问，以便应用程序可以使用不同的实现。
The command set is split into the following categories: mandatory to support, optional, and additional. The commands are extensible for new features and for value-add by implementations.
命令集分为以下类别：必须支持、可选和附加。这些命令对于新功能和实现的增值是可扩展的。
The Looking Glass command set is described as a language-independent concept. Consequently, any programming language that satisfies the commands listed in the following sections is acceptable.
窥镜命令集被描述为一个独立于语言的概念。因此，任何满足以下部分中列出的命令的编程语言都是可以接受的。
This work is not the output of the IETF and is presented in the hope that Looking Glass implementers will offer a common programmable interface.
这项工作不是IETF的输出，它的目的是希望Looking Glass实现者能够提供一个通用的可编程接口。
The requirement of a uniform access to a Looking Glass service becomes important when multiple Looking Glasses are part of a monitoring system. Implementing a web client and HTTP parser for every kind of web-based Looking Glass is a time-consuming workaround. However, the Looking Glass command set is a much more viable, compatible, and scalable solution.
当多个窥镜是监控系统的一部分时，统一访问窥镜服务的要求变得非常重要。为每种基于web的窥镜实现web客户端和HTTP解析器是一种耗时的解决方法。然而，lookingglass命令集是一个更加可行、兼容和可扩展的解决方案。
This specification uses the JavaScript Object Notation (JSON) of [RFC8259] arranged as JSend-compliant (Appendix A) responses.
本规范使用[RFC8259]的JavaScript对象表示法（JSON）作为符合JSend的响应（附录A）进行排列。
All URLs in this documentation use the reserved sample domain of "example.net" as defined in Section 6.5 of [RFC6761].
本文档中的所有URL均使用[RFC6761]第6.5节中定义的保留示例域“example.net”。
The URLs further use the fixed [RFC5785] prefix of ".well-known/ looking-glass" to prevent a collision in the domain's namespace.
URL进一步使用固定的[RFC5785]前缀“.well-known/looking glass”来防止域名称空间中的冲突。
IPv4 addresses use the documentation block of 192.0.2.0/24 [RFC5737] and IPv6 addresses reside in the reserved prefix of 2001:DB8::/32 [RFC3849]. BGP Autonomous System (AS) numbers are chosen from the private AS range defined in [RFC6996].
IPv4地址使用192.0.2.0/24[RFC5737]的文档块，IPv6地址位于保留前缀2001:DB8:：/32[RFC3849]中。BGP自治系统（AS）编号从[RFC6996]中定义的专用AS范围中选择。
The examples skip some required parameters for reasons of simplicity.
为了简单起见，示例跳过了一些必需的参数。
A client issues a query using the HTTP GET method to request specific resources from the server. The resource is a URI and can be informational or a command execution. The client must present all necessary parameters for the server to execute the command on the selected router. Every call is stateless and independent of the previous one.
客户端使用HTTP GET方法发出查询，以从服务器请求特定资源。资源是URI，可以是信息资源，也可以是命令执行资源。客户端必须提供服务器在所选路由器上执行命令所需的所有参数。每个调用都是无状态的，独立于前一个调用。
The path component of the resource URI must use the prefix of ".well-known/looking-glass" (see Section 5.1) to stay namespace neutral.
资源URI的路径组件必须使用前缀“.well-known/looking glass”（参见第5.1节）来保持名称空间中立。
The "call" is a request from the client that specifies a predefined operation ("function") that the server will execute on a selected router. The "command" is a task executed on the router and initiated by the server on behalf of the client. The type and scope of all commands are defined and limited by the server. The client must not be able to execute random commands on the targeting router. There must not be any direct communication between the client and the router.
“调用”是来自客户端的请求，指定服务器将在选定路由器上执行的预定义操作（“功能”）。“命令”是在路由器上执行的任务，由服务器代表客户端启动。所有命令的类型和范围都由服务器定义和限制。客户端不能在目标路由器上执行随机命令。客户端和路由器之间不得有任何直接通信。
After the execution of the command on the selected router has finished, the server replies to the client if the operation has either succeeded, failed, or timed out. The response is sent to the client in JSON format. The communication protocol used between the server and router is not specified by this document; any method (e.g., Telnet, SSH, NETCONF, serial console) is acceptable.
在所选路由器上执行命令完成后，如果操作成功、失败或超时，服务器将回复客户端。响应以JSON格式发送到客户端。本文件未规定服务器和路由器之间使用的通信协议；任何方法（如Telnet、SSH、NETCONF、串行控制台）都是可以接受的。
All parameters and their values are case insensitive.
所有参数及其值都不区分大小写。
Method parameters are mandatory components of the URI and are placed in the "path" section in terms of [RFC7320]. Basically, the method parameters specify the call and determine which command the client wants to be executed on the selected router.
方法参数是URI的必需组件，并根据[RFC7320]放置在“路径”部分。基本上，方法参数指定调用并确定客户端希望在所选路由器上执行的命令。
Query parameters are optional components of the URI and are placed in the "query" section in terms of [RFC7320]. Generally, the query parameters are additional instructions for the requested command.
查询参数是URI的可选组件，根据[RFC7320]放置在“查询”部分。通常，查询参数是请求命令的附加指令。
protocol Restrict the command and method parameters to use the specified protocol and version. Protocol is selected as "Address Family Identifier" [IANA-AFN] [RFC4760] and optionally as "Subsequent Address Family Identifier" [IANA-SAFI] separated by a comma. Default value is 1,1 (IP version 4, unicast). JSON datatype is String. Examples:
协议限制命令和方法参数使用指定的协议和版本。协议被选择为“地址族标识符”[IANA-AFN][RFC4760]，并可选地选择为“后续地址族标识符”[IANA-SAFI]，用逗号分隔。默认值为1,1（IP版本4，单播）。JSON数据类型是字符串。示例：
* protocol=2,1 (IP version 6, unicast)
* 协议=2,1（IP版本6，单播）
* protocol=26 (MPLS, no SAFI used)
* 协议=26（MPLS，未使用SAFI）
router Run the command on the router identified by its name. This is not necessarily the router's hostname as long as the Looking Glass software recognizes it. Default value is the first router in the list of available routers. JSON datatype is String. Example: router=rbgn06.example.net
路由器在由其名称标识的路由器上运行命令。只要Looking Glass软件能够识别，这不一定是路由器的主机名。默认值是可用路由器列表中的第一个路由器。JSON数据类型是字符串。示例：router=rbgn06.Example.net
routerindex Run the command on this router identified by its position in the list of available routers. Default value is "0". JSON datatype is Number. Example: routerindex=8
routerindex在此路由器上运行命令，该命令由其在可用路由器列表中的位置标识。默认值为“0”。JSON数据类型是数字。示例：routerindex=8
random Append a random string to prevent the client (or an intermediate proxy) from caching the response. The server must ignore its value. No default value. JSON datatype is String. Example: random=517A93B50
随机附加随机字符串以防止客户端（或中间代理）缓存响应。服务器必须忽略其值。没有默认值。JSON数据类型是字符串。示例：random=517A93B50
vrf Run the command from the selected routing table. This parameter is valid only on routers that support "Virtual Routing and Forwarding" (VRF). No default value. JSON datatype is String. Example: vrf=mgmt
vrf从所选路由表运行命令。此参数仅在支持“虚拟路由和转发”（VRF）的路由器上有效。没有默认值。JSON数据类型是字符串。示例：vrf=mgmt
runtime Stop executing the command after the runtime limit (in seconds) is exceeded. A value of 0 disables the limit. Default value is "30". JSON datatype is Number. Example: runtime=60
超过运行时限制（以秒为单位）后，运行时停止执行命令。值为0将禁用该限制。默认值为“30”。JSON数据类型是数字。示例：运行时=60
format Request the server to provide the output (if any) in the selected format. Specify multiple formats separated by a comma in descending order of preference. See Section 3.3.2 for more details. Default value is "text/plain" (raw/unformatted output). JSON datatype is String. Example: format=application/yang,text/plain
格式化请求服务器以所选格式提供输出（如果有）。按首选项的降序顺序指定以逗号分隔的多种格式。详见第3.3.2节。默认值为“文本/普通”（原始/未格式化输出）。JSON数据类型是字符串。示例：format=application/yang，text/plain
The HTTP response header contains an appropriate HTTP status code as defined in [RFC7231] with the Content-Type set to "application/json".
HTTP响应头包含[RFC7231]中定义的适当HTTP状态代码，内容类型设置为“application/json”。
The HTTP body contains details and error descriptions. The response text must comply with the JSON syntax specification JSend, which is briefly explained in Appendix A. Consequently, every response must contain a "status" field of either "success", "fail", or "error" as explained in the following sections.
HTTP正文包含详细信息和错误描述。响应文本必须符合JSON语法规范JSend，该规范在附录A中有简要说明。因此，每个响应必须包含“成功”、“失败”或“错误”的“状态”字段，如下节所述。
A successful response must set the "status" field to "success". It must also contain a "data" object including the following information:
成功的响应必须将“状态”字段设置为“成功”。它还必须包含包含以下信息的“数据”对象：
performed_at Combined date and time in UTC ISO 8601 [iso8601] indicating when the operation finished. This information must be present.
在UTC ISO 8601[iso8601]中的日期和时间组合执行，指示操作完成的时间。这些信息必须存在。
runtime Amount of seconds (wallclock) used to run the command. This information must be present.
运行时用于运行命令的秒数（wallclock）。这些信息必须存在。
router Name of the router that executed the command. This information may be present.
路由器执行命令的路由器的名称。此信息可能存在。
output Output of the command in a format that was requested by the client; it otherwise defaults to raw output as it appeared on the router's command-line interface (CLI). It might even be blank if the command did not produce any output. This information should be present.
以客户端请求的格式输出命令；否则，它默认为原始输出，就像它出现在路由器的命令行界面（CLI）上一样。如果命令不产生任何输出，它甚至可能为空。这些信息应该存在。
format Selected output format by the server. The client might request multiple formats so that the "Looking Glass" server has to choose the best option and tell the client which format was selected. This information should be present (defaults to "text/plain" if missing).
格式化服务器选择的输出格式。客户端可能会请求多种格式，因此“窥镜”服务器必须选择最佳选项，并告诉客户端选择了哪种格式。应提供此信息（如果缺少，则默认为“文本/普通”）。
Adding more information to the response is permitted and must be placed inside the "data" object.
允许向响应中添加更多信息，并且必须将其放置在“数据”对象中。
The HTTP status code should be 200.
HTTP状态代码应为200。
Example:
例子：
HTTP/1.1 200 OK
Content-Type: application/json
{
"status" : "success",
"data" : {
"router" : "route-server.lookingglass.example.net"
"performed_at" : "2014-10-15T17:15:34Z",
"runtime" : 2.63,
"output" : [
"full raw output from the observing router..."
],
"format" : "text/plain"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status" : "success",
"data" : {
"router" : "route-server.lookingglass.example.net"
"performed_at" : "2014-10-15T17:15:34Z",
"runtime" : 2.63,
"output" : [
"full raw output from the observing router..."
],
"format" : "text/plain"
}
}
A status of "fail" indicates that the selected command was executed on the router but failed to succeed. The response message must set the "status" field to "fail" and must contain the "data" object with command-specific content listed in Section 2.3.1.
“失败”状态表示所选命令已在路由器上执行，但未能成功。响应消息必须将“状态”字段设置为“失败”，并且必须包含第2.3.1节中列出的具有命令特定内容的“数据”对象。
The HTTP status code should be 200.
HTTP状态代码应为200。
Example:
例子：
HTTP/2.0 200 OK
{
"status" : "fail",
"data" : {
"performed_at" : "2014-10-18T20:04:37Z",
"runtime" : 10.37,
"output" : [
"Sending 5, 100-byte ICMP Echos to 192.0.2.5",
".....",
"Success rate is 0 percent (0/5)"
],
"format" : "text/plain",
"router" : "route-server.lookingglass.example.net"
}
}
HTTP/2.0 200 OK
{
"status" : "fail",
"data" : {
"performed_at" : "2014-10-18T20:04:37Z",
"runtime" : 10.37,
"output" : [
"Sending 5, 100-byte ICMP Echos to 192.0.2.5",
".....",
"Success rate is 0 percent (0/5)"
],
"format" : "text/plain",
"router" : "route-server.lookingglass.example.net"
}
}
The status "error" represents either that the command timed out or that an error occurred in processing the request. The response message must set the "status" field to "error" and must contain the "message" key, which keeps a meaningful message, explaining what went wrong.
状态“error”表示命令超时或处理请求时出错。响应消息必须将“status”字段设置为“error”，并且必须包含“message”键，该键保存有意义的消息，解释出错的原因。
The response may contain the "data" key with required values listed in Section 2.3.1. It may also include a "code" field that carries a numeric code corresponding to the error.
响应可能包含第2.3.1节中列出的具有所需值的“数据”键。它还可能包括一个“代码”字段，该字段携带与错误对应的数字代码。
The HTTP status code should be 400 in case of a client-side error, 500 in case of a server-side error, or 502 for errors occurring on the target router. Code 504 should be used when a command timed out.
如果发生客户端错误，HTTP状态代码应为400；如果发生服务器端错误，HTTP状态代码应为500；如果发生在目标路由器上的错误，HTTP状态代码应为502。命令超时时应使用代码504。
Example:
例子：
HTTP/1.1 400 Bad Request
{
"status" : "error",
"message" : "Unrecognized host or address."
}
HTTP/1.1 400 Bad Request
{
"status" : "error",
"message" : "Unrecognized host or address."
}
The Looking Glass command set provides functions that are either mandatory to support or optional to implement. The same principle applies to the web-based Looking Glass.
Looking Glass命令集提供了支持的必需功能或实现的可选功能。同样的原理也适用于基于网络的窥镜。
It is not possible for any function to modify the server's state. Therefore, all HTTP methods are GET operations.
任何函数都不可能修改服务器的状态。因此，所有HTTP方法都是GET操作。
Variables are templated and expanded in accordance with [RFC6570].
变量按照[RFC6570]进行模板化和扩展。
Send echo messages to validate the reachability of a remote host and measure round-trip time. The host can be a name or address.
发送回显消息以验证远程主机的可达性并测量往返时间。主机可以是名称或地址。
Implementation of the ping command is mandatory.
必须执行ping命令。
Syntax: https://example.net/.well-known/looking-glass/v1/ping/{host}
Syntax: https://example.net/.well-known/looking-glass/v1/ping/{host}
Example query:
查询示例：
GET /.well-known/looking-glass/v1/ping/2001:DB8::35?protocol=2,1
Host: example.net
GET /.well-known/looking-glass/v1/ping/2001:DB8::35?protocol=2,1
Host: example.net
Example response:
答复示例：
HTTP/1.1 200 OK
{
"status" : "success",
"data" : {
"min" : 40,
"avg" : 41,
"max" : 44,
"rate" : 100,
"output" : [
"Sending 5, 100-byte ICMP Echos to 2001:DB8::35",
"!!!!!",
"Success rate is 100 percent (5/5)"
],
"format" : "text/plain",
"performed_at" : "2014-10-04T14:40:58Z",
"runtime" : 0.77,
"router" : "c2951.lab.lg.example.net"
}
}
HTTP/1.1 200 OK
{
"status" : "success",
"data" : {
"min" : 40,
"avg" : 41,
"max" : 44,
"rate" : 100,
"output" : [
"Sending 5, 100-byte ICMP Echos to 2001:DB8::35",
"!!!!!",
"Success rate is 100 percent (5/5)"
],
"format" : "text/plain",
"performed_at" : "2014-10-04T14:40:58Z",
"runtime" : 0.77,
"router" : "c2951.lab.lg.example.net"
}
}
Trace the path from the executing router to the destination host and list all intermediate hops. The host can be a name or address.
跟踪从执行路由器到目标主机的路径，并列出所有中间跃点。主机可以是名称或地址。
Implementation of the traceroute command is optional.
traceroute命令的实现是可选的。
Syntax: https://example.net/.well-known/looking-glass/v1/
traceroute/{host}
Syntax: https://example.net/.well-known/looking-glass/v1/
traceroute/{host}
Example query:
查询示例：
GET /.well-known/looking-glass/v1/traceroute/192.0.2.8?routerindex=5
Host: example.net
GET /.well-known/looking-glass/v1/traceroute/192.0.2.8?routerindex=5
Host: example.net
Example response:
答复示例：
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"Tracing the route to 192.0.2.8",
"",
" 1 198.51.100.77 28 msec 28 msec 20 msec",
" 2 203.0.113.130 52 msec 40 msec 40 msec",
" 3 192.0.2.8 72 msec 76 msec 68 msec"
],
"format": "text/plain",
"performed_at": "2018-06-10T12:09:31Z",
"runtime": 4.21,
"router": "c7206.lab.lg.example.net"
}
}
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"Tracing the route to 192.0.2.8",
"",
" 1 198.51.100.77 28 msec 28 msec 20 msec",
" 2 203.0.113.130 52 msec 40 msec 40 msec",
" 3 192.0.2.8 72 msec 76 msec 68 msec"
],
"format": "text/plain",
"performed_at": "2018-06-10T12:09:31Z",
"runtime": 4.21,
"router": "c7206.lab.lg.example.net"
}
}
Retrieve information about a specific subnet from the routing table.
从路由表中检索有关特定子网的信息。
Implementation of the "show route" command is mandatory.
必须执行“显示路线”命令。
Syntax: https://example.net/.well-known/looking-glass/v1/show/
route/{addr}
Syntax: https://example.net/.well-known/looking-glass/v1/show/
route/{addr}
Example query:
查询示例：
GET /.well-known/looking-glass/v1/show/ [multiline]
route/2001:DB8::/48?protocol=2,1
Host: example.net
GET /.well-known/looking-glass/v1/show/ [multiline]
route/2001:DB8::/48?protocol=2,1
Host: example.net
Example response:
答复示例：
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"S 2001:DB8::/48 [1/0]",
" via FE80::C007:CFF:FED9:17, FastEthernet0/0"
],
"format": "text/plain",
"performed_at": "2018-06-11T17:13:39Z",
"runtime": 1.39,
"router": "c2951.lab.lg.example.net"
}
}
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"S 2001:DB8::/48 [1/0]",
" via FE80::C007:CFF:FED9:17, FastEthernet0/0"
],
"format": "text/plain",
"performed_at": "2018-06-11T17:13:39Z",
"runtime": 1.39,
"router": "c2951.lab.lg.example.net"
}
}
Display a matching record from the BGP routing table. This should include networks, next hop, and may include metric, local preference, path list, weight, etc.
显示BGP路由表中的匹配记录。这应该包括网络、下一跳，并且可能包括度量、本地首选项、路径列表、权重等。
Implementation of the "show bgp" command is optional.
“show bgp”命令的实现是可选的。
Syntax: https://example.net/.well-known/looking-glass/v1/show/
bgp/{addr}
Syntax: https://example.net/.well-known/looking-glass/v1/show/
bgp/{addr}
Example query:
查询示例：
GET /.well-known/looking-glass/v1/show/bgp/192.0.2.0/24
Host: example.net
GET /.well-known/looking-glass/v1/show/bgp/192.0.2.0/24
Host: example.net
Example response:
答复示例：
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"BGP routing table entry for 192.0.2.0/24, version 2",
"Paths: (2 available, best #2, table default)",
" Advertised to update-groups:",
" 1",
" Refresh Epoch 1",
" Local",
" 192.0.2.226 from 192.0.2.226 (192.0.2.226)",
" Origin IGP, metric 0, localpref 100, valid, internal",
"[...]"
],
"format": "text/plain",
"performed_at": "2018-06-11T21:47:17Z",
"runtime": 2.03,
"router": "c2951.lab.lg.example.net"
}
}
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"BGP routing table entry for 192.0.2.0/24, version 2",
"Paths: (2 available, best #2, table default)",
" Advertised to update-groups:",
" 1",
" Refresh Epoch 1",
" Local",
" 192.0.2.226 from 192.0.2.226 (192.0.2.226)",
" Origin IGP, metric 0, localpref 100, valid, internal",
"[...]"
],
"format": "text/plain",
"performed_at": "2018-06-11T21:47:17Z",
"runtime": 2.03,
"router": "c2951.lab.lg.example.net"
}
}
Print a summary of BGP neighbor status. This may include the neighbor BGP ID, autonomous system number, duration of peering, number of received prefixes, etc.
打印BGP邻居状态的摘要。这可能包括邻居BGP ID、自治系统号、对等持续时间、接收前缀的数量等。
Implementation of the "show bgp summary" command is optional.
“show bgp summary”命令的实现是可选的。
Syntax: https://example.net/.well-known/looking-glass/v1/show/bgp/
summary
Syntax: https://example.net/.well-known/looking-glass/v1/show/bgp/
summary
Example:
例子：
GET /.well-known/looking-glass/v1/show/bgp/summary? [multiline]
protocol=2&routerindex=3
Host: example.net
GET /.well-known/looking-glass/v1/show/bgp/summary? [multiline]
protocol=2&routerindex=3
Host: example.net
Example response:
答复示例：
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"BGP router identifier 192.0.2.18, local AS number 64501",
"BGP table version is 85298, main routing table version 85298",
"50440 network entries using 867568 bytes of memory",
"[...]",
"Neighbor V AS MsgRcvd MsgSent TblVer Up/Down",
"2001:DB8:91::24 4 64500 481098 919095 85298 41w5d"
],
"format": "text/plain",
"performed_at": "2018-06-11T21:59:21Z",
"runtime": 1.91,
"router": "c2951.lab.lg.example.net"
}
}
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"BGP router identifier 192.0.2.18, local AS number 64501",
"BGP table version is 85298, main routing table version 85298",
"50440 network entries using 867568 bytes of memory",
"[...]",
"Neighbor V AS MsgRcvd MsgSent TblVer Up/Down",
"2001:DB8:91::24 4 64500 481098 919095 85298 41w5d"
],
"format": "text/plain",
"performed_at": "2018-06-11T21:59:21Z",
"runtime": 1.91,
"router": "c2951.lab.lg.example.net"
}
}
Provide detailed information on BGP neighbor connections. Available details may include neighbor BGP ID, advertised networks, learned networks, autonomous system number, capabilities, protocol, statistics, etc.
提供有关BGP邻居连接的详细信息。可用的详细信息可能包括邻居BGP ID、广告网络、学习网络、自治系统编号、能力、协议、统计信息等。
Implementation of the "show bgp neighbors" command is optional.
“显示bgp邻居”命令的实现是可选的。
Syntax: https://example.net/.well-known/looking-glass/v1/show/bgp/
neighbors/{addr}
Syntax: https://example.net/.well-known/looking-glass/v1/show/bgp/
neighbors/{addr}
Example query:
查询示例：
GET /.well-known/looking-glass/v1/show/bgp/neighbors/192.0.2.226
Host: example.net
GET /.well-known/looking-glass/v1/show/bgp/neighbors/192.0.2.226
Host: example.net
Example response:
答复示例：
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"BGP neighbor is 192.0.2.226, remote AS 64500, internal link",
" BGP version 4, remote router ID 198.51.100.31",
" BGP state = Established, up for 01:24:06",
"[...]"
],
"format": "text/plain",
"performed_at": "2018-06-11T21:41:17Z",
"runtime": 1.87,
"router": "c2951.lab.lg.example.net"
}
}
HTTP/1.1 200 OK
{
"status": "success",
"data": {
"output": [
"BGP neighbor is 192.0.2.226, remote AS 64500, internal link",
" BGP version 4, remote router ID 198.51.100.31",
" BGP state = Established, up for 01:24:06",
"[...]"
],
"format": "text/plain",
"performed_at": "2018-06-11T21:41:17Z",
"runtime": 1.87,
"router": "c2951.lab.lg.example.net"
}
}
The following organizational commands must be included in the implementation.
实现中必须包括以下组织命令。
Provides a full list of routers that are available for command execution. This list includes the router ID and its name. It is equivalent to the common "router" HTML drop-down form element and contains the same information.
提供可用于命令执行的路由器的完整列表。此列表包括路由器ID及其名称。它相当于常见的“router”HTML下拉表单元素，包含相同的信息。
Syntax: https://example.net/.well-known/looking-glass/v1/routers
Syntax: https://example.net/.well-known/looking-glass/v1/routers
Example response:
答复示例：
{
"status" : "success",
"data" : {
"routers" : [
"route-server.lookingglass.example.net",
"customer-edge.lookingglass.example.net",
"provider-edge.lookingglass.example.net"
],
"performed_at" : "2014-10-19T20:07:01Z",
"runtime" : 0.73
}
}
{
"status" : "success",
"data" : {
"routers" : [
"route-server.lookingglass.example.net",
"customer-edge.lookingglass.example.net",
"provider-edge.lookingglass.example.net"
],
"performed_at" : "2014-10-19T20:07:01Z",
"runtime" : 0.73
}
}
Lists additional information about the selected router specified by its router index. The response must contain the router's hostname and router index. The response may contain more details like output format, country code, city, administrative contact, vendor, and model.
列出由路由器索引指定的选定路由器的其他信息。响应必须包含路由器的主机名和路由器索引。响应可能包含更多详细信息，如输出格式、国家代码、城市、管理联系人、供应商和型号。
Available output formats are specified by Internet media type as of [RFC6838] and listed in [IANA-MT]. If the routers support multiple formats, they are separated by a comma.
可用的输出格式由[RFC6838]起的互联网媒体类型指定，并在[IANA-MT]中列出。如果路由器支持多种格式，则用逗号分隔。
The router might provide output formats that are not yet registered or listed in [IANA-MT]. For example, output in NETCONF format could use "text/x.netconf". [RFC6838] provides a tree for unregistered subtypes.
路由器可能提供尚未在[IANA-MT]中注册或列出的输出格式。例如，NETCONF格式的输出可以使用“text/x.NETCONF”。[RFC6838]为未注册的子类型提供树。
A missing output format defaults to "text/plain", which is a copy of the raw command-line output.
缺少的输出格式默认为“text/plain”，它是原始命令行输出的副本。
Syntax: https://example.net/.well-known/looking-glass/v1/
routers/{number}
Syntax: https://example.net/.well-known/looking-glass/v1/
routers/{number}
Example query:
查询示例：
GET /.well-known/looking-glass/v1/routers/1
Host: example.net
GET /.well-known/looking-glass/v1/routers/1
Host: example.net
Example response:
答复示例：
{
"status" : "success",
"data" : {
"id" : 1,
"name" : "customer-edge.lookingglass.example.net",
"format" : "text/plain,text/x.netconf",
"country" : "de",
"autonomous_system" : 64512
}
}
{
"status" : "success",
"data" : {
"id" : 1,
"name" : "customer-edge.lookingglass.example.net",
"format" : "text/plain,text/x.netconf",
"country" : "de",
"autonomous_system" : 64512
}
}
Provides a full list of commands that are available for execution. The list includes mandatory to support, optional, and additional (Section 3.4) commands. It is equivalent to the "command" HTML drop-down or radio-button form element and contains the same information.
提供可供执行的命令的完整列表。该列表包括强制支持、可选和附加（第3.4节）命令。它相当于“command”HTML下拉列表或单选按钮表单元素，并且包含相同的信息。
The list is formatted as a "commands" array containing one object per command. This object contains informative strings about the current command: href, arguments, description, and command.
列表格式为“commands”数组，每个命令包含一个对象。此对象包含有关当前命令的信息字符串：href、参数、说明和命令。
Syntax: https://example.net/.well-known/looking-glass/v1/cmd
Syntax: https://example.net/.well-known/looking-glass/v1/cmd
Example response:
答复示例：
{
"status" : "success",
"data" : {
"commands" : [
{
"href" : "https://example.net/.well-known/ [multiline]
looking-glass/v1/show/route",
"arguments" : "{addr}",
"description" : "Print records from IP routing table",
"command" : "show route"
},
{
"href" : "https://example.net/.well-known/ [multiline]
looking-glass/v1/traceroute",
"arguments" : "{addr}",
"description" : "Trace route to destination host",
"command" : "traceroute"
}
]
}
}
{
"status" : "success",
"data" : {
"commands" : [
{
"href" : "https://example.net/.well-known/ [multiline]
looking-glass/v1/show/route",
"arguments" : "{addr}",
"description" : "Print records from IP routing table",
"command" : "show route"
},
{
"href" : "https://example.net/.well-known/ [multiline]
looking-glass/v1/traceroute",
"arguments" : "{addr}",
"description" : "Trace route to destination host",
"command" : "traceroute"
}
]
}
}
The list of commands discussed in Section 3.3.3 may be expanded as long as the principles of this document are observed.
只要遵守本文件的原则，第3.3.3节中讨论的命令列表可以扩展。
For example, a Looking Glass provider may not be offering BGP-related commands because of an OSPF-based network.
例如，由于基于OSPF的网络，窥镜提供商可能不提供BGP相关命令。
The sample command might be:
示例命令可能是：
GET /.well-known/looking-glass/v1/show/ospf/database
Host: example.net
GET /.well-known/looking-glass/v1/show/ospf/database
Host: example.net
The network traffic sent by a "Looking Glass" is not appropriate when measuring Service Level Agreements or validating Quality of Service settings.
在测量服务级别协议或验证服务质量设置时，“窥镜”发送的网络流量不合适。
If a monitoring system uses the Looking Glass command set for reachability checks, it should not rely on the HTTP status codes but on the "status" message field inside the HTTP body.
如果监控系统使用Looking Glass命令集进行可达性检查，则不应依赖HTTP状态代码，而应依赖HTTP正文中的“status”（状态）消息字段。
This specification registers a Well-Known URI [RFC5785]:
本规范注册了一个众所周知的URI[RFC5785]：
URI Suffix: looking-glass
URI后缀：镜子
Change Controller: M. Stubbig
更改控制器：M.Stubbig
Reference : This document, Section 2
参考：本文件第2节
The use of HTTPS is required to ensure a high level of security, privacy, and confidentiality during transit.
需要使用HTTPS来确保传输过程中的高度安全性、隐私性和机密性。
The main goal of the Looking Glass command set is the automated usage of the Looking Glass service. This allows the scripting of API calls, which could be used as a Distributed Denial of Service (DDoS) attack. It is recommended that implementers of the Looking Glass API take steps to mitigate the above described abuse. The strategy can include blocking or rate-limiting by client IP address or target IP network.
lookingglass命令集的主要目标是自动使用lookingglass服务。这允许编写API调用脚本，可将其用作分布式拒绝服务（DDoS）攻击。建议lookglassapi的实现者采取措施来缓解上述滥用。该策略可以包括通过客户端IP地址或目标IP网络进行阻塞或速率限制。
Authentication is not a requirement because the current Looking Glass web services are usable without authentication. Requests to the proposed API service may be authenticated by any method. The decision is up to the implementer's security requirements.
身份验证不是必需的，因为当前的lookglass web服务在没有身份验证的情况下是可用的。对提议的API服务的请求可以通过任何方法进行认证。决策取决于实现者的安全需求。
Some of the described commands provide a detailed insight into the provider's network. It is therefore up to the implementer's security policy to dismiss commands that are marked as "optional" or to restrict commands that are marked as "mandatory".
所描述的一些命令提供了对提供商网络的详细了解。因此，由实现者的安全策略决定是否拒绝标记为“可选”的命令或限制标记为“必需”的命令。
[IANA-AFN] IANA, "Address Family Numbers", <https://www.iana.org/ assignments/address-family-numbers/>.
[IANA-AFN]IANA，“地址系列号”<https://www.iana.org/ 分配/地址系列号/>。
[IANA-MT] IANA, "Media Types", <https://www.iana.org/assignments/media-types/>.
[IANA-MT]IANA，“媒体类型”<https://www.iana.org/assignments/media-types/>.
[IANA-SAFI] IANA, "Subsequent Address Family Identifiers (SAFI) Parameters", <https://www.iana.org/assignments/safi-namespace/>.
[IANA-SAFI]IANA，“后续地址系列标识符（SAFI）参数”<https://www.iana.org/assignments/safi-namespace/>.
[JSend] OmniTI Labs, "JSend", 2014, <https://labs.omniti.com/labs/jsend>.
[JSend]OmniTI实验室，“JSend”，2014年<https://labs.omniti.com/labs/jsend>.
[RFC4760] Bates, T., Chandra, R., Katz, D., and Y. Rekhter, "Multiprotocol Extensions for BGP-4", RFC 4760, DOI 10.17487/RFC4760, January 2007, <https://www.rfc-editor.org/info/rfc4760>.
[RFC4760]Bates，T.，Chandra，R.，Katz，D.，和Y.Rekhter，“BGP-4的多协议扩展”，RFC 4760，DOI 10.17487/RFC4760，2007年1月<https://www.rfc-editor.org/info/rfc4760>.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010, <https://www.rfc-editor.org/info/rfc5785>.
[RFC5785]诺丁汉，M.和E.Hammer Lahav，“定义众所周知的统一资源标识符（URI）”，RFC 5785，DOI 10.17487/RFC5785，2010年4月<https://www.rfc-editor.org/info/rfc5785>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, March 2012, <https://www.rfc-editor.org/info/rfc6570>.
[RFC6570]Gregorio，J.，Fielding，R.，Hadley，M.，Nottingham，M.，和D.Orchard，“URI模板”，RFC 6570，DOI 10.17487/RFC657012年3月<https://www.rfc-editor.org/info/rfc6570>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <https://www.rfc-editor.org/info/rfc7231>.
[RFC7231]Fielding，R.，Ed.和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：语义和内容”，RFC 7231，DOI 10.17487/RFC72312014年6月<https://www.rfc-editor.org/info/rfc7231>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/info/rfc8259>.
[RFC8259]Bray，T.，Ed.“JavaScript对象表示法（JSON）数据交换格式”，STD 90，RFC 8259，DOI 10.17487/RFC8259，2017年12月<https://www.rfc-editor.org/info/rfc8259>.
[iso8601] International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", December 2004.
[iso8601]国际标准化组织，“数据元素和交换格式-信息交换-日期和时间的表示”，2004年12月。
[RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix Reserved for Documentation", RFC 3849, DOI 10.17487/RFC3849, July 2004, <https://www.rfc-editor.org/info/rfc3849>.
[RFC3849]Huston，G.，Lord，A.，和P.Smith，“保留用于文档的IPv6地址前缀”，RFC 3849，DOI 10.17487/RFC3849，2004年7月<https://www.rfc-editor.org/info/rfc3849>.
[RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks Reserved for Documentation", RFC 5737, DOI 10.17487/RFC5737, January 2010, <https://www.rfc-editor.org/info/rfc5737>.
[RFC5737]Arkko，J.，Cotton，M.和L.Vegoda，“为文档保留的IPv4地址块”，RFC 5737，DOI 10.17487/RFC5737，2010年1月<https://www.rfc-editor.org/info/rfc5737>.
[RFC6761] Cheshire, S. and M. Krochmal, "Special-Use Domain Names", RFC 6761, DOI 10.17487/RFC6761, February 2013, <https://www.rfc-editor.org/info/rfc6761>.
[RFC6761]Cheshire，S.和M.Krochmal，“特殊用途域名”，RFC 6761，DOI 10.17487/RFC6761，2013年2月<https://www.rfc-editor.org/info/rfc6761>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <https://www.rfc-editor.org/info/rfc6838>.
[RFC6838]Freed，N.，Klensin，J.和T.Hansen，“介质类型规范和注册程序”，BCP 13，RFC 6838，DOI 10.17487/RFC6838，2013年1月<https://www.rfc-editor.org/info/rfc6838>.
[RFC6996] Mitchell, J., "Autonomous System (AS) Reservation for Private Use", BCP 6, RFC 6996, DOI 10.17487/RFC6996, July 2013, <https://www.rfc-editor.org/info/rfc6996>.
[RFC6996]Mitchell，J.，“供私人使用的自主系统（AS）预订”，BCP 6，RFC 6996，DOI 10.17487/RFC6996，2013年7月<https://www.rfc-editor.org/info/rfc6996>.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 7320, DOI 10.17487/RFC7320, July 2014, <https://www.rfc-editor.org/info/rfc7320>.
[RFC7320]诺丁汉，M.，“URI设计和所有权”，BCP 190，RFC 7320，DOI 10.17487/RFC7320，2014年7月<https://www.rfc-editor.org/info/rfc7320>.
According to [JSend]:
根据[JSend]：
JSend is a specification that lays down some rules for how JSON responses from web servers should be formatted. JSend focuses on application-level (as opposed to protocol- or transport-level) messaging which makes it ideal for use in REST-style applications and APIs.
JSend是一个规范，它为如何格式化来自web服务器的JSON响应制定了一些规则。JSend专注于应用程序级（与协议或传输级相反）消息传递，这使得它非常适合在REST风格的应用程序和API中使用。
A basic JSend-compliant response must contain a "status" key and should contain "data", "message", and "code" keys dependent on the status value. The following table lists the required and optional keys.
符合JSend的基本响应必须包含“status”键，并且应该包含依赖于status值的“data”、“message”和“code”键。下表列出了所需键和可选键。
+---------+-----------------+---------------+
| Type | Required keys | Optional keys |
+---------+-----------------+---------------+
| success | status, data | |
| fail | status, data | |
| error | status, message | code, data |
+---------+-----------------+---------------+
+---------+-----------------+---------------+
| Type | Required keys | Optional keys |
+---------+-----------------+---------------+
| success | status, data | |
| fail | status, data | |
| error | status, message | code, data |
+---------+-----------------+---------------+
Table 1: Type and Keys in JSend Response
表1:JSend响应中的类型和键
Author's Address
作者地址
Markus Stubbig Independent Germany
马库斯·斯塔比独立德国
Email: stubbig.ietf@gmail.com
Email: stubbig.ietf@gmail.com