--- 0.20200107-group.txt +++ 0.20200227.1-CC.txt @@ -1,11 +1,11 @@ PeeringDB Data Ownership Policy Document -Date: TBA -Version: 0.20200107-group +Date: TBD +Version: 0.20200227.1-CC 1) Background -The Data Ownership Task Force was established in September 2019 with the +The Data Ownership Task Force was established in September, 2019, with the aim of working on a PeeringDB Policy proposal about data ownership, after a need was recognized by the Product Committee as issues consistently had been raised relating to who owns the data in PeeringDB when more than one @@ -34,186 +34,586 @@ After the publishing of the Policy Document, the Task Force will end. - 3) Overarching Principles 3.1) Purpose of PeeringDB -PeeringDB is a network data-sharing platform, not a marketing tool. -Maybe make reference the AUP. - -3.2) Expectations from Users of PeeringDB - -- Data is expected to be consistent and correct following good - engineering. - -- Users are expected to do their utmost to keep their data up-to-date at - any given time. - -3.3) PeeringDB / Admin Committee can treat incorrect data by (?) - -- We do this because we want to make sure we have good quality data. - -- Delete/override them or flag them? - -- Clean-ups done by +From https://www.peeringdb.com/about as of February 26th, 2020: -- Curated vs user-submitted data - how do we word this? + - PeeringDB, as the name suggests, was set up to facilitate peering + between networks and peering coordinators. In recent years, the vision + of PeeringDB has developed to keep up with the speed and diverse manner + in which the Internet is growing. The database is no longer just for + peering and peering related information. It now includes all types of + interconnection data for networks, clouds, services, and enterprise, as + well as interconnection facilities that are developing at the edge of + the Internet. + + - We believe in, and rely on the community to grow and improve the + PeeringDB database. The volunteers who run the database are passionate + about security, privacy, integrity, and validation of the data in the + database. Even though PeeringDB is a freely available and public tool, + users strictly adhere to the acceptable use policy + (https://www.peeringdb.com/aup), which prevents the database being used + for commercial purposes and discourages unsolicited communications. + This is largely policed by the community and has been very effective + since PeeringDB was launched. + +3.2) Expectations + + - Data is expected to be consistent and correct following good + engineering. + + - Users are expected to keep their Organization's data current. + +3.3) Admin Committee + +The PeeringDB Admin Committee may alter data. This is done because as a +community we want to make sure we have good quality data. Depending on the +circumstances, data may be deleted, hidden, overridden, or flagged. The +Admin Committee may perform research and/or involve multiple parties in +order help resolve matters. -- Ack Admins manipulating or at least investigating issues about data? - -- File a complaint and Admins investigate (?) - -Admin Committee is the group that deals with data creation and -updates from users. They have their own documentation and logging systems -as they deal with user data. TF recommends this practice continues as +The Admin Committee has their own ticketing and logging systems as they +deal with user data. This task force recommends this practice continue as having audit trails of all data is good practice. -3.4) In some cases ownership may not be either-or, but may carry nuances. -These nuances are this and that... +3.4) Conflicted Data -Do we take the physical port speed for example? +In some cases ownership of data elements may not be either/or, but rather +may be nuanced. For example, an Internet Exchange (IX) may have shared an +IP assignment with a new participant in advance of updating the IX's +public records, some of which may be processed by PeeringDB in an +automated fashion. This can result in a conflict based on PeeringDB +receiving differing information from two sources. -4) Data Description +4) High Level Data Descriptions PeeringDB's mission is to facilitate the exchange of user-maintained interconnection related information. This information is presented in data -relating to entities known mainly as Organisations, Internet Exchanges, -Facilities, Networks, and Point of Contacts in the Internet industry. -Derived from that is data relating to where Networks and Internet -Exchanges are, and to which Internet Exchange Networks are connected to. - -4.1) Internet Exchanges - -PeeringDB accepts the general industry understanding of Internet Exchange -Points; an infrastructure used by an operator to provide multilateral and -bi-lateral connections between participating networks. - -Internet Exchange Points allow their participants create presence records -in PeeringDB, that they are peering at the IX. - -A point of demarcation for an IX is the cross-connect or connection where -the Facility (see below) it lives in provides connectivity to the -end-users of the IX, local or remote. Internal to the IX, infrastructure -includes switches, route servers and operational support systems. - -In the current implementation of PeeringDB Internet Exchange Points are -represented in "ix", "ixlan", "ixpfx", "netixlan", and "netfac" objects. - -One can find the following as the major information among IX records: +relating to entities known mainly as Organizations, Points of Contact, +Facilities, Internet Exchanges, and Networks in the Internet industry. +Derived from that is data relating to where Networks and IXs are located, +and to which IXs, Networks are connected to. -- the relevant Organization running the IX (URL to the "org" object), +4.1) Organizations -- Contact Information, +PeeringDB uses the term Organization to refer to the holding entity for +any number of IXs, Facilities, and Networks. -- Peering LANs (blocks IPv4 and IPv6 numbers that are allocated/assigned - to Internet Exchanges by relevant registries) of Internet Exchange - Points ("ixlan" and "ixpfx" objects), +4.2) Points of Contact -- Peers at the Internet Exchange Point and the specific IPs that each - participant gets assigned to at the Internet Exchange to enable peering - with others ("netixlan" objects), +PeeringDB uses the term Point of Contact to refer to individuals or roles +along with optional name, email, and telephone information. -- Local Facilities that the IX is present in ("ixfac" objects) - -4.2) Facilities +4.3) Facilities PeeringDB uses the term Facility to record data centers which are centralized locations where computing and networking equipment of tenants -are located. Within the scope of PeeringDB, Facilities can house Internet -Exchange Points and other Networks where these entities can establish -interconnection. - -In the current implementation, this is represented in "fac" object. - -[Are we talking about physical presence here? ] -Facility can know who is and who is not present at a facility (?). - -Possibility of having two-way authorisation to solve this problem: -FAC says yes to ISP, ISP says yes to FAC. - -TCS - -Facilities have a technical and legal meaning in many jurisdictions. In -Australia, the legal meaning of facilities includes pits, pipes, data -centre buildings and communication towers. - -Facilities, broadly can be defined as sets of telecommunications -infrastructure that supports the housing of service providers, networks -and internet exchange points. - -It's like asking: where does your IXP reside? +are located. Within the scope of PeeringDB, Facilities can house IXs and +Networks, and these entities can establish interconnection. -4.3) Networks +In the current implementation of PeeringDB, Facilities are +referenced in "fac", "ixfac", and "netfac" objects. -Describe Network +One can find the following as the major information among Facility +records: -4.4) How do these main data correlate with each other? +- the relevant Organization managing the Facility - ("org"), -Describe the need for derived objects. -ixfac -ixlan -ixpfx -netfac -netixlan +- IXs and Networks at the Facility - ("ixfac", "netfac") -4.5) Other Data +4.4) Internet Exchanges -Describe the need for as_set and POCs +The definition of an IX or Internet Exchange Point is beyond the scope of +this document. At a minimum, an IX is a communications fabric where +independent networks may engage in Internet Protocol peering - exchange of +Internet data. -4.6) Recommendations/Considerations by the TF? +PeeringDB provides methods for both IXs and Networks to indicate the +participation of a network at an IX. -Do we think we need other objects to help to have the correct data in -PeeringDB as the Data Ownership TF? +IXs may be present at one or more Facilities, and may indicate this in +PeeringDB. -5) Data Elements in PeeringDB +In the current implementation of PeeringDB, IXs are referenced in "ix", +"ixfac", "ixlan", "ixpfx", and "netixlan" objects. -This section lists the data elements that are listed in PeeringDB -API as listed in https://peeringdb.com/apidocs/ +One can find the following as the major information among IX records: -For each object description, attributes/values (?) and who can update is listed below. -At the end of the section there is a Table as an executive summary. +- the relevant Organization managing the IX - ("org"), -5.1) as_set +- Contact Information - ("poc"), -Description: -Attributes/values: -Who owns and updates: +- Peering Local Area Networks (LANs) (MTU and VLAN details) of IXs - + ("ixlan"), -Add Image from PeeringDB??? +- Peering LANs (IPv4 and IPv6 subnets) of IXs - ("ixpfx"), -5.2) fac +- Peers at the IX and the specific IP addresses assigned to each + participant - ("netixlan"), -5.3) ix - -5.4) ixfac - -5.5) ixlan - -5.6) ixpfx - -5.7) net - -5.8) netfac - -5.9) netixlan - -5.10) org +- Facilities that the IX is present at - ("ixfac") + +4.5) Networks -5.11) poc +A PeeringDB Network is a network with a globally unique Autonomous System +Number (ASN). +In the current implementation of PeeringDB, Networks are referenced in +"net", "netfac", and "netixlan" objects. -Table: Executive Summary +One can find the following as the major information among Network records: + +- the relevant Organization managing the Network - ("org"), + +- Contact Information - ("poc"), + +- Network at an IX - ("netixlan") + +- Network at a Facility - ("netfac") + +5) Data Elements in PeeringDB + +This section lists the data elements that are listed in PeeringDB API as +listed at: + + https://peeringdb.com/apidocs/ + +For each data element, attributes/values and who can update them is listed +below. At the end of the section there is a Table as an executive summary. + +5.1) Single-party data elements. + +These data elements contain data provided by a single party. + +5.1.1) as_set + +- Internet Routing Registry (IRR) as-set/route-set from "net" data + element. + +- The "net" data element from which this API result is derived, has a + parent "org" reference. Users with sufficient permission in the + Organization represented by that "org" data element are able to create, + update, and delete this "as_set" information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/as_set/65512 + - Result: + + { + "65512": "AS-EXAMPLE" + } + +5.1.2) fac + +- "fac" represents a Facility. Information such as the name, location, + and website are contained within the "fac" data element. + +- The "fac" data element has a parent "org" reference. Users with + sufficient permission in the Organization represented by that "org" + data element are able to create, update, and delete this "fac" + information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/fac/# + - Result: + + { + "id": #, + "org_id": ##, + "org_name": "Example Building Owners", + "org": {}, + "name": "Example Building", + "website": "https://www.building.example/", + "clli": "STTLWA", + "rencode": "", + "npanxx": "206-443", + "notes": "", + "net_count": 150, + "latitude": 47.6062, + "longitude": -122.3321, + "created": "2001-07-01T00:00:00Z", + "updated": "2020-07-01T20:15:05Z", + "status": "ok", + "address1": "123 Main", + "address2": "Suite 321", + "city": "Seattle", + "country": "US", + "state": "WA", + "zipcode": "90000" + } + +5.1.3) ix + +- "ix" represents an Internet Exchange. Information such as the name, + location, website, and contact information are contained within the "ix" + data element. + +- The "ix" data element has a parent "org" reference. Users with + sufficient permission in the Organization represented by that "org" + data element are able to create, update, and delete this "ix" + information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/ix/# + - Result: + + { + "id": #, + "org_id": ##, + "org": {}, + "name": "Example IX", + "name_long": "Example Internet Exchange", + "city": "Seattle", + "country": "US", + "region_continent": "North America", + "media": "Ethernet", + "notes": "EIX port fees: etc.\n", + "proto_unicast": true, + "proto_multicast": false, + "proto_ipv6": true, + "website": "https://www.eix.example/", + "url_stats": "https://www.eix.example/statistics/", + "tech_email": "info@eix.example", + "tech_phone": "+12065551212", + "policy_email": "info@eix.example", + "policy_phone": "", + "fac_set": [], + "ixlan_set": [], + "net_count": 317, + "created": "2010-07-29T00:00:00Z", + "updated": "2020-01-22T06:32:52Z", + "status": "ok" + } + +5.1.4) ixlan + +- "ixlan" represents some aspects of an Internet Exchange LAN such as the + LAN name, description, MTU, and VLAN identifier if any. It also points + to both the "ix" and "ixpfx" data elements. + +- The "ixlan" data element points to an "ix" data element, which has a + parent "org" reference. Users with sufficient permission in the + Organization represented by that "org" data element are able to create, + update, and delete this "ixlan" information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/ixlan/# + - Result: + + { + "id": #, + "ix_id": #, + "ix": {}, + "name": "MTU 1500", + "descr": "", + "mtu": 1500, + "dot1q_support": false, + "rs_asn": 0, + "arp_sponge": null, + "net_set": [], + "ixpfx_set": [], + "created": "2010-07-29T00:00:00Z", + "updated": "2019-05-08T03:57:10Z", + "status": "ok" + } + +5.1.5) ixpfx + +- "ixpfx" represents the IP subnet of IP assignments on an Internet + Exchange LAN. It also points to both the associated "ixlan" data + element. + +- The "ixpfx" data element points to an "ixlan" data element, which points + to an "ix" data element, which has a parent "org" reference. Users with + sufficient permission in the Organization represented by that "org" + data element are able to create, update, and delete this "ixpfx" + information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/ixpfx/# + - Result: + + { + "id": #, + "ixlan": {}, + "ixlan_id": ##, + "protocol": "IPv4", + "prefix": "192.0.2.0/24", + "created": "2010-07-29T00:00:00Z", + "updated": "2016-03-14T21:38:00Z", + "status": "ok" + } + +5.1.6) net + +- "net" represents a Network. Information such as the name, website, ASN, + as-set/route-set, prefix counts, type of network, traffic ratios, + policies, etc. are contained within the "net" data element. + +- The "net" data element has a parent "org" reference. Users with + sufficient permission in the Organization represented by that "org" + data element are able to create, update, and delete this "net" + information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/net/# + - Result: + + { + "id": #, + "org_id": ##, + "org": {}, + "name": "Widget Corporation", + "aka": "Widgets R Us", + "website": "https://www.widgets.example/", + "asn": 65512, + "looking_glass": "", + "route_server": "", + "irr_as_set": "AS-EXAMPLE", + "info_type": "Content", + "info_prefixes4": 5, + "info_prefixes6": 1, + "info_traffic": "", + "info_ratio": "Balanced", + "info_scope": "Global", + "info_unicast": true, + "info_multicast": false, + "info_ipv6": true, + "info_never_via_route_servers": false, + "notes": "", + "policy_url": "https://www.widgets.example/peering.html", + "policy_general": "Open", + "policy_locations": "Not Required", + "policy_ratio": false, + "policy_contracts": "Not Required", + "netfac_set": [], + "netixlan_set": [], + "poc_set": [], + "created": "2005-02-01T10:16:50Z", + "updated": "2019-10-04T16:43:46Z", + "status": "ok" + } + +5.1.7) org + +- "org" represents an Organization. Information such as the name, website, + and address are contained within the "org" data element. + +- Users with sufficient permission in the Organization represented by this + data element are able to create, update, and delete this "org" + information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/org/# + - Result: + + { + "id": #, + "name": "Widget Conglomerate", + "website": "https://www.widgets.example/", + "notes": "", + "net_set": [], + "fac_set": [], + "ix_set": [], + "address1": "123 Example St", + "address2": "", + "city": "Seattle", + "country": "US", + "state": "WA", + "zipcode": "90000", + "created": "2005-02-01T10:16:50Z", + "updated": "2019-10-04T16:33:10Z", + "status": "ok" + } + +5.1.8) poc + +- "poc" represents a Point of Contact. Information such as the name or + role name, visibility setting, telephone number, email address, and URL + are contained within the "poc" data element. + +- The "poc" data element points to a "net" data element, which has a + parent "org" reference. Users with sufficient permission in the + Organization represented by that "org" data element are able to create, + update, and delete this "poc" information. + +- The Admin Committee is also able to adjust this record under their + discretion, such as at the request of the managing organization. + +- Example: + - Query: https://www.peeringdb.com/api/poc/# + - Result: + + { + "id": #, + "net_id": ##, + "net": {}, + "role": "NOC Example", + "visible": "Users", + "name": "Joe Example", + "phone": "206-555-1212", + "email": "noc@widget.example", + "url": "", + "created": "2010-07-29T00:00:00Z", + "updated": "2016-03-14T20:31:04Z", + "status": "ok" + } + +5.2) Multi-party data elements. + +These data elements can contain data provided by multiple parties. In +cases of conflict between the data sources, the PeeringDB Admin Committee +may become involved to help resolve differences. In addition, the +PeeringDB user interface may help guide participants toward harmony. + +5.2.1) netixlan + +- "netixlan" represents the IP address assignments for a Network at an + Internet Exchange. These assignments are normally made by the Internet + Exchange and provided to the Network. + +- The "netixlan" data element points to a "net" data element, which has a + parent "org" reference. Users with sufficient permission in the + Organization represented by that "org" data element are able to create, + update, and delete this "netixlan" information. In addition, Networks + may take advantage of automated mechanisms that PeeringDB offers, which + utilize data publicly exported by Internet Exchanges. + +- A conflict may arise in which the IP assignment data publicly exported + by an Internet Exchange does not match data provided by a Network. + Alternatively, an Internet Exchange may reach out to PeeringDB to + dispute the IP assignment data provided by a Network. + + Since this data can have an impact on Internet operations, this document + specifies a principle of minimal disruption. This principle means that + conflicted data which is already published shall not be taken down + unless done so by the Network or by a resolution process mediated by the + Admin Committee. + + Similarly, conflicted data which has not been published shall not be + published until a resolution process has been mediated by the Admin + Committee. + + PeeringDB may also employ user interface methods to encourage data + harmony between a Network and an Internet Exchange, as a means of + expediting resolution and decreasing the burdens on the Admin Committee. + +- Example: + - Query: https://www.peeringdb.com/api/netixlan/# + - Result: + + { + "id": #, + "net_id": ##, + "net": {}, + "ix_id": ###, + "name": "Example IX", + "ixlan_id": ###, + "ixlan": {}, + "notes": "", + "speed": 10000, + "asn": 65512, + "ipaddr4": "192.0.2.10", + "ipaddr6": "2001:db8::10", + "is_rs_peer": true, + "created": "2010-07-29T00:00:00Z", + "updated": "2019-03-02T03:15:13Z", + "status": "ok" + } + +5.2.2) ixfac + +- "ixfac" represents the presence of an Internet Exchange at a Facility. + +- The "ixfac" data element points to an "ix" data element, which has a + parent "org" reference. Users with sufficient permission in the + Organization represented by that "org" data element are able to create, + update, and delete this "ixfac" information. + +- While all Facilities have a parent Organization data element, not all of + those Organizations in PeeringDB have actual Users. Some Facilities are + the result of suggestions by other Users, while other Facilities are the + product of the migration from PeeringDB 1.x to PeeringDB 2.x. + +- A conflict may arise in which a Facility with an actual owner disputes + the presence of an Internet Exchange at their Facility. In this case, + the Admin Committee is empowered to mediate a resolution process. + +- Example: + - Query: https://www.peeringdb.com/api/ixfac/# + - Result: + + { + "id": #, + "ix_id": ##, + "ix": {}, + "fac_id": ###, + "fac": {}, + "created": "2010-07-29T00:00:00Z", + "updated": "2016-03-14T21:44:51Z", + "status": "ok" + } + +5.2.3) netfac + +- "netfac" represents the presence of a Network at a Facility. This + information can include the name of the Facility, the location, and the + ASN employed by the Network at the location. + +- The "netfac" data element points to an "net" data element, which has a + parent "org" reference. Users with sufficient permission in the + Organization represented by that "org" data element are able to create, + update, and delete this "netfac" information. + +- While all Facilities have a parent Organization data element, not all of + those Organizations in PeeringDB have actual Users. Some Facilities are + the result of suggestions by other Users, while other Facilities are the + product of the migration from PeeringDB 1.x to PeeringDB 2.x. + +- A conflict may arise in which a Facility with an actual owner disputes + the presence of a Network at their Facility. In this case, the Admin + Committee is empowered to mediate a resolution process. + +- Example: + - Query: https://www.peeringdb.com/api/netfac/# + - Result: + + { + "id": #, + "name": "Example Building", + "city": "Seattle", + "country": "US", + "net_id": ##, + "net": {}, + "fac_id": ###, + "fac": {}, + "local_asn": 65512, + "created": "2010-07-29T00:00:00Z", + "updated": "2016-03-14T21:02:43Z", + "status": "ok" + } -Object Type Attributes/Values Owner -as_set -fac -ix -ixfac -ixlan -ixpfx -net -netfac -netixlan -org -poc +END