[tor-dev] Standardizing the 'onion service' name

[Damian Johnson]

Hi all, teor suggested engaging the list with #25918 so here we go!
Ticket #25918 has a couple goals...

1. Provide a tracking ticket for the rename effort.
2. Come to a consensus on if we should move forward with "onion
service" or revert back to "hidden service". The limbo we've been in
for months is confusing for our users and we should standardize on a
name.

Here's the ticket...

========================================

A recent post on tor-dev@ just got me thinking about the roadblocks we
have for v2 deprecation. There's a couple I don't believe we're
following in trac so lets fix that.

For me the biggest is its name. Renaming takes work, and we attempted
to rename hidden services in v3 without investing the time to make it
happen. We should either fix that or revert to to the old name. To
move forward we need to...

Have OnionService aliases for controller commands, events, descriptor
fields, and anything else referencing 'HS' or 'HiddenService'.

Speaking of which, how do we plan to replace abbreviations? Having an
'OSFETCH' or 'OS_CREATED' event doesn't exactly have the same ring as
their HS counterparts. ;P

Adjust all our docs to be consistent about the name.

Renaming takes work. Lesson I learned from Nyx is that it works best
if you draw a line in the sand and stand by it. With Nyx, version 2.0
is called Nyx (you won't find any docs saying otherwise) and version
1.x is the legacy 'arm' project.

If I was in your shoes I'd opt for the same. Either prioritize the
aliases and be firm that v3 are 'Onion Services' or abort the rename.
Otherwise this will live in a confusing dual-named limbo land
indefinitely. ;P

Cheers! -Damian

PS. Stem and Nyx have stuck with the old name ("hidden services") and
will continue to do so until tor's standardized this.

[Paul Syverson]

Post by Damian Johnson
Hi all, teor suggested engaging the list with #25918 so here we go!
Ticket #25918 has a couple goals...
1. Provide a tracking ticket for the rename effort.
2. Come to a consensus on if we should move forward with "onion
service" or revert back to "hidden service". The limbo we've been in
for months is confusing for our users and we should standardize on a
name.

I'm very confused why you say that this is not a long solved problem.
I see nothing in the recent posts about v2 deprecation that would in
any way change that, or even raise it as a topic.

When talking in general to people, the answer should be that they are
all (v2 and v3) onion services. That's it. I believe this is the
official position of the Tor Project, and they have worked hard to
make sure that this is reflected on any new materials on the site for
some time. I'm cc'ing Steph in case she is not on the tor-dev list
and wants to say anything further on that point.

I'll respond to other comments inline below. Feel free to add my comments
to the ticket if you want, but IMO there is no reason a ticket should
exist at all for this.

Post by Damian Johnson
Here's the ticket...
========================================
have for v2 deprecation. There's a couple I don't believe we're
following in trac so lets fix that.
For me the biggest is its name. Renaming takes work, and we attempted
to rename hidden services in v3 without investing the time to make it
happen. We should either fix that or revert to to the old name. To
move forward we need to...

I don't understand this at all. We have renamed hidden services to be
called 'onion services' some time ago. I don't know what it is that
you feel we didn't make happen. 'Hidden services' was an old name for
onion services that has always been misleading narrow about the nature
of these services and thus long in need of replacing (and actually the
name we originally and for some time used was 'location hidden
services' though 'location' simply started getting more and more
ignored along the way). "Misleadingly narrow" because some of their
central properties are ignored by calling them 'hidden services',
viz. the stronger and more-site-owner-controlled authentication these
services provide and their address lookup security vs. the less secure
parts of the internet served by DNS.

Post by Damian Johnson
Have OnionService aliases for controller commands, events, descriptor
fields, and anything else referencing 'HS' or 'HiddenService'.
Speaking of which, how do we plan to replace abbreviations? Having an
'OSFETCH' or 'OS_CREATED' event doesn't exactly have the same ring as
their HS counterparts. ;P
Adjust all our docs to be consistent about the name.

Right, anything v3 should be consistently calling these 'onion
services'. Variable names, etc. particularly those still in use in
code shared with v2, don't need to be changed. It is OK if such
vestiges of older usage remain in abbreviations, as long as the
description of them, e.g., in any new Tor proposal, describes them
with appropriately current terminology.

Post by Damian Johnson
Renaming takes work. Lesson I learned from Nyx is that it works best
if you draw a line in the sand and stand by it. With Nyx, version 2.0
is called Nyx (you won't find any docs saying otherwise) and version
1.x is the legacy 'arm' project.
If I was in your shoes I'd opt for the same. Either prioritize the
aliases and be firm that v3 are 'Onion Services' or abort the rename.
Otherwise this will live in a confusing dual-named limbo land
indefinitely. ;P

I'm prettty sure that v3 being 'onion services' has been the official
Tor Project position since at least half a year. We wouldn't be
aborting the rename, because 'abort' would imply it is not
complete. Anything now not using the current name is not part of an
incomplete process, it is simply wrong and outdated. Steph correct me
if I am wrong about that.

So I think you've answered your own question. Nothing in v3 should be
called 'hidden services'. And anything new in code and documentation
should be called 'onion services'. If you want to think of v2 and
earlier as 'hidden services' for purposes of understanding legacy
component and variable names, e.g., HSDir that's fine. And as such,
variable names, etc. in code that continues to be used for both v2 and
v3 can can persist. But again, any new specs, documentation, etc.
should call them 'onion services'.

This acceptance of existing v2 documentation calling them 'hidden
services' while refusing this for anything v3 is a little misleading
about when and why the naming transition happened, but its close
enough to serve as your line in the sand if you feel one is needed.
I actually argued the value of essentially such a line-in-the-sand
position to Steph a while ago. This doesn't preclude also calling v2
and earlier 'onion services'. Indeed, it's not just OK but preferable,
for the above mentioned reasons.

aloha,
Paul

[teor]

Hi All,

There seems to be some confusion in this thread about the
current state of the hidden service to onion service name transition.

So I'm going to describe the state of things as they are, then try to
describe what would need to be done.

I'd also appreciate feedback from Steph and others on our priorities for
transitioning to the onion service name. I think we have been prioritising
user-facing text. (The blog, website, Tor Browser, metrics, etc.)

Is this a sensible way of prioritising things?

Post by Paul Syverson

Post by Damian Johnson
Have OnionService aliases for controller commands, events,

These are current called "hidden service" or an abbreviation.

Tor could add an alias mechanism for controller commands, events,
and fields, and use it to do the rename:

https://trac.torproject.org/projects/tor/ticket/25922

I don't think they are as high a priority as the torrc options and man page.

Post by Paul Syverson

Post by Damian Johnson
descriptor
fields

These are currently called "hidden service", or an abbreviation.

Descriptor fields are part of the directory specification and
implementation, and they are highly technical. So I'm not sure we gain
much from aliasing them or renaming them.

Similar arguments might apply to other codebases:
* Onionoo
* stem
* consensus health
* Tor (network daemon)

But the following user-facing applications should add documentation or
change names, if they haven't already:
* Relay Search / metrics website
* uses HSDir for relay search, because that's what it's called in the
directory protocol
* uses "onion service" for statistics
* Tor Browser
* uses "onion site"
* the Tor website
* new tor blog posts

Post by Paul Syverson

Post by Damian Johnson
and anything else referencing 'HS' or 'HiddenService'.

We considered adding OnionService* torrc option aliases for every
HiddenService* option in 0.2.9. But we deferred that change because we
ran out of time.

All we need to do is add some new entries in the alias table, then do a
search and replace in the tor man page:
https://trac.torproject.org/projects/tor/ticket/17343

Post by Paul Syverson

Post by Damian Johnson
Speaking of which, how do we plan to replace abbreviations? Having an
'OSFETCH' or 'OS_CREATED' event doesn't exactly have the same ring as
their HS counterparts. ;P

That's a good question.

OS conflicts with "operating system", so we could use:
* Onion
* OnSrv
* no abbreviations
Or any other colour you want to paint the bikeshed.

To avoid an endless discussion, let's leave the decision to
the people who write, review, and merge the code.

Post by Paul Syverson

Post by Damian Johnson
Adjust all our docs to be consistent about the name.

Right, anything v3 should be consistently calling these 'onion
services'. Variable names, etc. particularly those still in use in
code shared with v2, don't need to be changed. It is OK if such
vestiges of older usage remain in abbreviations, as long as the
description of them, e.g., in any new Tor proposal, describes them
with appropriately current terminology.

torrc options, the tor man page, and the v3 onion service code
mainly use "hidden service", and sometimes use "onion service".

I don't see much value in changing the code.

If we decide there is value in changing the torrc options and man page,
we need to allocate a few days of work on the roadmap to make it
happen.

Post by Paul Syverson

Post by Damian Johnson
Renaming takes work. Lesson I learned from Nyx is that it works best
if you draw a line in the sand and stand by it. With Nyx, version 2.0
is called Nyx (you won't find any docs saying otherwise) and version
1.x is the legacy 'arm' project.
If I was in your shoes I'd opt for the same. Either prioritize the
aliases and be firm that v3 are 'Onion Services' or abort the rename.
Otherwise this will live in a confusing dual-named limbo land
indefinitely. ;P

I'm prettty sure that v3 being 'onion services' has been the official
Tor Project position since at least half a year. We wouldn't be
aborting the rename, because 'abort' would imply it is not
complete. Anything now not using the current name is not part of an
incomplete process, it is simply wrong and outdated. Steph correct me
if I am wrong about that.
So I think you've answered your own question. Nothing in v3 should be
called 'hidden services'.

That's not the current state of the tor network daemon v3 onion service
code, specs, options, and man page. They use a mix of terminology
(see above).

Post by Paul Syverson
And anything new in code and documentation
should be called 'onion services'. If you want to think of v2 and
earlier as 'hidden services' for purposes of understanding legacy
component and variable names, e.g., HSDir that's fine. And as such,
variable names, etc. in code that continues to be used for both v2 and
v3 can can persist. But again, any new specs, documentation, etc.
should call them 'onion services'.

We have gradually been using onion services in new documentation and
specs, since "single onion services". But we haven't changed existing
code and documentation.

Post by Paul Syverson
This acceptance of existing v2 documentation calling them 'hidden
services' while refusing this for anything v3 is a little misleading
about when and why the naming transition happened, but its close
enough to serve as your line in the sand if you feel one is needed.
I actually argued the value of essentially such a line-in-the-sand
position to Steph a while ago. This doesn't preclude also calling v2
and earlier 'onion services'. Indeed, it's not just OK but preferable,
for the above mentioned reasons.

It looks like we are doing a gradual transition. I think we prioritised
the things that are seen by the most users (Tor Browser, statistics,
blog, website).

We did not take a line in the sand position in the past, but we could
adopt one for the remaining changes. We could decide on a particular
Tor release (and releases of other codebases). But we need to schedule
the work on the relevant roadmaps.

And maybe there are some obscure technical things (code, comments,
descriptor fields) that just aren't worth changing.

T

[Paul Syverson]

Thanks teor for spelling things out in moderate detail and Steph for
commenting.

My tl;dr is to basically concur with everything they both said: The
further from user-facing and the more embedded down in the codebase,
variables, code comments, controller commands, etc. the less important
to spend effort eliminating such vestiges from existing text. Going
forward, certainly any code comments and e.g. any commands that won't
break things should use current terminology.

aloha,
Paul

Hi!
Thanks for adding me to the thread.

Post by teor
Hi All,
There seems to be some confusion in this thread about the
current state of the hidden service to onion service name transition.
So I'm going to describe the state of things as they are, then try to
describe what would need to be done.
I'd also appreciate feedback from Steph and others on our priorities for
transitioning to the onion service name. I think we have been prioritising
user-facing text. (The blog, website, Tor Browser, metrics,  etc.)

Yes, user, funder, and press facing text has consistently been using
onion services at least since I've been on board. When I first joined,
the message to me was that this was changed a couple years prior but
changeover had been slow. I realize now a lot of folks didn't get that
message.
We have already, with the help of Kat, updated hidden to onion services
where possible on the website. I think the exception to this is older
blog posts.
I realize it is not as easy to change some of the other elements, like
the directory protocol, but I think it's important to make what changes
are possible. I think it'd have a very positive impact to see these
through.
Being aligned will help us build trust with the press, new users, etc.
There are several reasons the name changed, if it is helpful to share
more about that lmk.

Post by teor
Is this a sensible way of prioritising things?

Post by Paul Syverson

Post by Damian Johnson
Have OnionService aliases for controller commands, events,

These are current called "hidden service" or an abbreviation.
Tor could add an alias mechanism for controller commands, events,
https://trac.torproject.org/projects/tor/ticket/25922
<https://trac.torproject.org/projects/tor/ticket/25922#ticket>
I don't think they are as high a priority as the torrc options and man page.

Post by Paul Syverson

Post by Damian Johnson
descriptor
fields

These are currently called "hidden service", or an abbreviation.
Descriptor fields are part of the directory specification and
implementation, and they are highly technical. So I'm not sure we gain
much from aliasing them or renaming them.
* Onionoo
* stem
* consensus health
* Tor (network daemon)
But the following user-facing applications should add documentation or
* Relay Search / metrics website
  * uses HSDir for relay search, because that's what it's called in the
    directory protocol
  * uses "onion service" for statistics
* Tor Browser
  * uses "onion site"
* the Tor website
* new tor blog posts

Website and new posts are covered.

Post by teor

Post by Paul Syverson

Post by Damian Johnson
and anything else referencing 'HS' or 'HiddenService'.

We considered adding OnionService* torrc option aliases for every
HiddenService* option in 0.2.9. But we deferred that change because we
ran out of time.
All we need to do is add some new entries in the alias table, then do a
https://trac.torproject.org/projects/tor/ticket/17343

Post by Paul Syverson

Post by Damian Johnson
Speaking of which, how do we plan to replace abbreviations? Having an
'OSFETCH' or 'OS_CREATED' event doesn't exactly have the same ring as
their HS counterparts. ;P

That's a good question.
* Onion
* OnSrv
* no abbreviations
Or any other colour you want to paint the bikeshed.
To avoid an endless discussion, let's leave the decision to
the people who write, review, and merge the code.

Post by Paul Syverson

Post by Damian Johnson
Adjust all our docs to be consistent about the name.

Right, anything v3 should be consistently calling these 'onion
services'.  Variable names, etc. particularly those still in use in
code shared with v2, don't need to be changed. It is OK if such
vestiges of older usage remain in abbreviations, as long as the
description of them, e.g., in any new Tor proposal, describes them
with appropriately current terminology.

torrc options, the tor man page, and the v3 onion service code
mainly use "hidden service", and sometimes use "onion service".
I don't see much value in changing the code.
If we decide there is value in changing the torrc options and man page,
we need to allocate a few days of work on the roadmap to make it
happen.

Post by Paul Syverson

Post by Damian Johnson
Renaming takes work. Lesson I learned from Nyx is that it works best
if you draw a line in the sand and stand by it. With Nyx, version 2.0
is called Nyx (you won't find any docs saying otherwise) and version
1.x is the legacy 'arm' project.
If I was in your shoes I'd opt for the same. Either prioritize the
aliases and be firm that v3 are 'Onion Services' or abort the rename.
Otherwise this will live in a confusing dual-named limbo land
indefinitely. ;P

I'm prettty sure that v3 being 'onion services' has been the official
Tor Project position since at least half a year. We wouldn't be
aborting the rename, because 'abort' would imply it is not
complete. Anything now not using the current name is not part of an
incomplete process, it is simply wrong and outdated. Steph correct me
if I am wrong about that.
So I think you've answered your own question. Nothing in v3 should be
called 'hidden services'.

Right. In our communications, all are onion services, there are just
different versions and configurations possible.
If I've missed something I can respond to more specifically in this
thread, please lmk.
-Steph

Post by teor
That's not the current state of the tor network daemon v3 onion service
code, specs, options, and man page. They use a mix of terminology
(see above).

Post by Paul Syverson
And anything new in code and documentation
should be called 'onion services'. If you want to think of v2 and
earlier as 'hidden services' for purposes of understanding legacy
component and variable names, e.g., HSDir that's fine. And as such,
variable names, etc. in code that continues to be used for both v2 and
v3 can can persist. But again, any new specs, documentation, etc.
should call them 'onion services'.

We have gradually been using onion services in new documentation and
specs, since "single onion services". But we haven't changed existing
code and documentation.

Post by Paul Syverson
This acceptance of existing v2 documentation calling them 'hidden
services' while refusing this for anything v3 is a little misleading
about when and why the naming transition happened, but its close
enough to serve as your line in the sand if you feel one is needed.
I actually argued the value of essentially such a line-in-the-sand
position to Steph a while ago. This doesn't preclude also calling v2
and earlier 'onion services'. Indeed, it's not just OK but preferable,
for the above mentioned reasons.

It looks like we are doing a gradual transition. I think we prioritised
the things that are seen by the most users (Tor Browser, statistics,
blog, website).
We did not take a line in the sand position in the past, but we could
adopt one for the remaining changes. We could decide on a particular
Tor release (and releases of other codebases). But we need to schedule
the work on the relevant roadmaps.
And maybe there are some obscure technical things (code, comments,
descriptor fields) that just aren't worth changing.
T