Specify MAC address format like this example 00-00-5E-00-53-23

[ypid-geberit]

Reasons for choosing this format:

• IEEE 802 uses this format: https://en.wikipedia.org/wiki/MAC_address#Notational_conventions
• IETF uses this format: https://tools.ietf.org/html/rfc7042

It is not yet clear if we should prefer upper or lowercase. I just went with uppercase for now because that is what the references above use.

Reason for choosing 00-00-5E-00-53-23:

It is in the range of unicast MAC addresses reserved for documentation as specified by: https://tools.ietf.org/html/rfc7042#section-2.1.2

Note that I did not update generated files because my development machine is not fully setup. Maybe you can update them real quick before merging? Thanks.

Edit: I moved the following from a comment below to here to have it in this overview comment:

It is also my observation that : are more commonly used and I am definitely also fine with going with those. When we setup our Logstash config for log parsing, we had to decide on a MAC address format (enforced by Logstash filters) and went with - for the above reasons. Here are some arguments for both of them (by no means comprehensive):

Pro :

• Linux (and lowercase)
• Android (and lowercase)

Pro -

• IEEE 802 (and uppercase): https://en.wikipedia.org/wiki/MAC_address#Notational_conventions
• IETF (and uppercase): https://tools.ietf.org/html/rfc7042
• Microsoft (and uppercase)

[webmat]

@ypid-geberit Thanks for the PR. No problem with the generated files, happy to pick this up and run the generator all the way.

The criteria I would like to use to determine the format, is ease of use for the end user. Aka make copy/paste easier ;-)

My understanding is that most tooling out there (monitoring, asset management, etc) use colon, rather than dash as the separator. For this reason I'm thinking colons would make more sense. I'd like to understand a bit more on why you favour the dashes over the colon, though.

As for upper/lowercase my criteria would also be the same, so I agree uppercase makes sense. However I'm also considering making this field case insensitive, but this will be more involved in how we document this, updating the sample ES templates etc. So out of scope for your PR :-)

So we can decide between - or : here, potentially adjust the example, but leave the capitalization underspecified for now. We'll tackle that part later.

[ebeahan]

I like the idea of including the example mac address from the reserved range, however I'm in favor of using : over - in the documentation. I agree with @webmat that most tooling seems to use the colon-separate notation.

[sgryphon]

The documentation change is fine. Should use "-", as that is what is specified in the standards (irrespective of whether some other systems don't follow them).

[andrewkroh]

In addition to updating the examples, the descriptions should be updated to specify the format. For example RFC7042 describes the notation as:

Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen.

I think we need to decide on a format so that implementations can start converging on a format. I don't have a strong opinion either way. But if there is an existing notation convention then I tend to think ECS should follow it.

[ebeahan]

I think we need to decide on a format so that implementations can start converging on a format. I don't have a strong opinion either way. But if there is an existing notation convention then I tend to think ECS should follow

@andrewkroh I wonder if we begin with introducing a recommendation in the field's description to normalize to the hyphen, with the intent to revisit and add firmer guidance in the future?

Outside of colon vs. hyphen, there are implementations using periods, EUI-48 vs. EUI-64, etc. Given many, many sources won't align with the notation convention and users will already be populating this field with a variety of formats, I'd prefer to hold off on introducing firm guidance.

//	00:00:5e:00:53:01
//	02:00:5e:10:00:00:00:01
//	00:00:00:00:fe:80:00:00:00:00:00:00:02:00:5e:10:00:00:00:01
//	00-00-5e-00-53-01
//	02-00-5e-10-00-00-00-01
//	00-00-00-00-fe-80-00-00-00-00-00-00-02-00-5e-10-00-00-00-01
//	0000.5e00.5301
//	0200.5e10.0000.0001
//	0000.0000.fe80.0000.0000.0000.0200.5e10.0000.0001

[ypid-geberit]

In addition to updating the examples, the descriptions should be updated to specify the format.

Done that.

I think we need to decide on a format so that implementations can start converging on a format. I don't have a strong opinion either way. But if there is an existing notation convention then I tend to think ECS should follow it.

I agree. There are two competing standards. Lets just go with one of them. Better than having implementers choose one at random.

Outside of colon vs. hyphen, there are implementations using periods, EUI-48 vs. EUI-64, etc. Given many, many sources won't align with the notation convention and users will already be populating this field with a variety of formats, I'd prefer to hold off on introducing firm guidance.

They need to update than when they want to comply with the next ECS version than. I see no big issue there.

I wonder if we begin with introducing a recommendation in the field's description to normalize to the hyphen, with the intent to revisit and add firmer guidance in the future?

So a soft migration? Or does this have other benefits?

[ebeahan]

So a soft migration? Or does this have other benefits?

Yes, the idea would be to introduce a recommended convention in a minor release and firm up the guidance on adopting later on.

[ebeahan]

@ypid-geberit Thanks for the iteration! I think we're very close; I have just one suggestion in the description's updated wording.

I'd be happy to add the generated files and get CI to ✅.

[ypid-geberit]

Works for me, done.

[ebeahan]

@elasticmachine, run elasticsearch-ci/docs

[ebeahan]

@elasticmachine, run elasticsearch-ci/docs

[ypid-geberit]

Thanks 👍🏾