[PDB Data Ownership-TF] draft "Data Ownership Policy Document"
William Marantz
wmarantz at salesforce.com
Thu Feb 27 08:45:34 PST 2020
thanks Chris, and thanks for catching my typo :)
Do you have any comment on the below?
> Is it already obvious, or do we want to be explicit that the netixlan
> conflict may be resolved by either side updating the data and that the
> Admin Committee would only involved for actively disputed data? I'd
> like to avoid the chance that someone gets the impression that the only
> way resolve a conflict and make once conflicted data visible is via the
> Admin Committee.
I'd also like to discuss the below section:
3.4) Conflicted Data
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.
I feel this section is really key to taskforce so I'd like to add
principles you mentioned later in the doc to this section.
Maybe something like the below:
In some cases ownership of data elements may not be either/or, but rather
may be nuanced. PeeringDB data is often used for Internet operations and
changes should not disrupt existing operational processes. This policy
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, PeeringDB automation explicitly authorized by the
Network, or by a resolution process mediated by the Admin Committee.
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.
Best Regards
-Bill
On Thu, Feb 27, 2020 at 11:23 AM Chris Caputo <ccaputo at alt.net> wrote:
> On Thu, 27 Feb 2020, William Marantz wrote:
> > Thanks for the hard work here Chris!!
> >
> > I'd like to discuss the following from the doc:
> >
> > 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.
> >
> > Is it already obvious, or do we want to be explicit that the netixlan
> > conflict may be resolved by either side updating the data and that the
> > Admin Committee would only involved for actively disputed data? I'd
> > like to avoid the chance that someone gets the impression that the only
> > way resolve a conflict and make once conflicted data visible is via the
> > Admin Committee.
> >
> > I'd like to change the 2nd sentence to the following which seems to
> > better align with the discussions of the TF and the discussions on the
> > open peeringDB git hub items :
> >
> > The taskforce recommends PeeringDB to employ user interface methods
> > and email notifications 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.
>
> Hi Bill,
>
> I am happy to insert this change, albeit with "PeeringDB to employ"
> changed to "PeeringDB employ".
>
> Please see the below draft and attached diff.
>
> Thanks and please let me know of other needed modifications.
>
> Chris
>
> ---
>
> PeeringDB Data Ownership Policy Document
>
> Date: TBD
> Version: 0.20200227.2-CC-WM
>
> 1) Background
>
> 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
> party is involved (ex: netixlan, ixfac, netfac).
>
> A call for participation to the Task Force was made on September 10th,
> 2019.
>
> 2) Scope
>
> The Data Ownership Task Force is established to discuss and agree on who
> owns the data tokens and/or objects in PeeringDB. Their agreements,
> findings, and any sort of recommendations will be documented in a Policy
> Document as a direct outcome of the Task Force.
>
> This Policy Document will include a clear description of each data element
> and the relation between each other, as well as who should be allowed to
> create, update, and delete them.
>
> The Task Force is estimated to conclude its work within about 6 months
> from its inception, which was September 2019. This time frame will be
> extended if the Task Force needs more time to conclude its work.
>
> The resulting Policy Document will be announced and shared with the
> PeeringDB Community.
>
> After the publishing of the Policy Document, the Task Force will end.
>
> 3) Overarching Principles
>
> 3.1) Purpose of PeeringDB
>
> From https://www.peeringdb.com/about as of February 26th, 2020:
>
> - 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.
>
> The Admin Committee has their own ticketing and logging systems as they
> deal with user data. The Task Force recommends this practice continue as
> having audit trails of all data is good practice.
>
> 3.4) Conflicted Data
>
> 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) 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 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.
>
> 4.1) Organizations
>
> PeeringDB uses the term Organization to refer to the holding entity for
> any number of IXs, Facilities, and Networks.
>
> 4.2) Points of Contact
>
> PeeringDB uses the term Point of Contact to refer to individuals or roles
> along with optional name, email, and telephone information.
>
> 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 IXs and
> Networks, and these entities can establish interconnection.
>
> In the current implementation of PeeringDB, Facilities are
> referenced in "fac", "ixfac", and "netfac" objects.
>
> One can find the following as the major information among Facility
> records:
>
> - the relevant Organization managing the Facility - ("org"),
>
> - IXs and Networks at the Facility - ("ixfac", "netfac")
>
> 4.4) Internet Exchanges
>
> 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.
>
> PeeringDB provides methods for both IXs and Networks to indicate the
> participation of a network at an IX.
>
> IXs may be present at one or more Facilities, and may indicate this in
> PeeringDB.
>
> In the current implementation of PeeringDB, IXs are referenced in "ix",
> "ixfac", "ixlan", "ixpfx", and "netixlan" objects.
>
> One can find the following as the major information among IX records:
>
> - the relevant Organization managing the IX - ("org"),
>
> - Contact Information - ("poc"),
>
> - Peering Local Area Networks (LANs) (MTU and VLAN details) of IXs -
> ("ixlan"),
>
> - Peering LANs (IPv4 and IPv6 subnets) of IXs - ("ixpfx"),
>
> - Peers at the IX and the specific IP addresses assigned to each
> participant - ("netixlan"),
>
> - Facilities that the IX is present at - ("ixfac")
>
> 4.5) Networks
>
> 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.
>
> 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 at eix.example",
> "tech_phone": "+12065551212",
> "policy_email": "info at 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 at 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.
>
> The Task Force recommends PeeringDB employ user interface methods and
> email notifications 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"
> }
>
> END
--
*Bill Marantz*
Principal Network Engineer
Backbone Engineering
Mobile: 848-404-4613
email: wmarantz at salesforce.com <ihamilton at salesforce.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.peeringdb.com/pipermail/dataownership-tf/attachments/20200227/582b01d2/attachment-0001.htm>
More information about the DataOwnership-TF
mailing list