Document TOR_PT_EXIT_ON_STDIN_CLOSE in the pt-spec.

This is the ticket for the documentation side of the TOR_PT_EXIT_ON_STDIN_CLOSE and associated behavior that was implemented as part of #15435 (moved).

pt-spec.txt needs to document that if the env var is set to 1, then PTs should assume that tor will keep stdin open, and to treat stdin being closed as the same as a SIGTERM (graceful shutdown immediately).

changed milestone to %Tor: 0.2.8.x-final

added 028-triaged component::circumvention/pluggable transport milestone::Tor: 0.2.8.x-final owner::yawning parent::16754 points::small pre028-patch priority::medium pt-spec pt-wants resolution::fixed severity::normal status::closed type::task labels

Interesting, the current revision of pt-spec.txt doesn't mention the SIGINT behavior at all. I guess this is ok, since it's not actually implemented in the tor side code, and I don't really see a good case for keeping it.

Anyway, this documents the PT termination behavior, including the shutdown on close stuff: https://github.com/Yawning/torspec/compare/bug15545

My plans going forward to bring some sanity to the PT shutdown process, now that TOR_PT_EXIT_ON_STDIN_CLOSE exists is to change the tor side PT teardown code to:

1. Close stdin (and on U*IX, send a SIGTERM, PT behavior here is equivalent).
2. Wait for a grace period (~1 sec?)
3. If the child still is not dead, send a SIGKILL/TerminateProcess().

I think that behavior reflects what's in the spec, is far more portable/sane than what currently exists, and will fix #9330 (moved) since PTs that have their own children will have ample time to clean up.

Trac:
Status: new to needs_revision

Repushed to use dcf's wording from #9732 (moved) (which my commit also fixes).

Trac:
Status: needs_revision to needs_review

#9741 (closed) should also probably go away as a wontfix if we're giving up on the SIGINT thing.

Replying to yawning:

Anyway, this documents the PT termination behavior, including the shutdown on close stuff: https://github.com/Yawning/torspec/compare/bug15545

There are some typo fixes that should be a separate commit.

+ 2.3. Extended ORPort
- versions of this configuration protocol Tor supports. Clients
+ versions of this configuration protocol Tor supports. Proxies
- too while performing the managed proxy protocol:
+ to while performing the managed proxy protocol:

A little typo "enviornment" (three times).

Instead of saying "by closing their listener ports, closing all existing connections, running other cleanup as required, and terminating" twice in two separate paragraphs, it's easier to understand if you first say what should happen on SIGTERM, and then say that if TOR_PT_EXIT_ON_STDIN_CLOSE=1, that stdin EOF has the same meaning as SIGTERM.

Trac:
Status: needs_review to needs_revision

Trac:
Parent: N/A to #16754 (moved)

Trac:
Milestone: Tor: 0.2.7.x-final to Tor: 0.2.8.x-final

Trac:
Keywords: pt-spec pt-wants deleted, 028-triaged, pt-wants, pt-spec added

Trac:
Cc: dcf, asn to dcf, asn, yawning
Points: N/A to small
Sponsor: N/A to N/A

Trac:
Keywords: N/A deleted, pre028-patch added

yawning: does your pt rewrite make this ticket obsolete?

Trac:
Severity: N/A to Normal

Indeed, the rewritten pt-spec includes documenting this behavior.

Trac:
Resolution: N/A to fixed
Status: needs_revision to closed

closed

mentioned in issue #15593 (moved)

moved to tpo/anti-censorship/pluggable-transports/trac#15545 (closed)

mentioned in issue tpo/anti-censorship/pluggable-transports/trac#15593 (moved)

mentioned in issue tpo/core/tor#40517 (closed)