capitalize environment variables

Development
1

Problem

Continuing the discussion from inform user that torbrowser won't start:

I was trying to avoid starting torbrowser from reading the script, and took some time to find tb_no_start.

  • it is an environment variable
    • should be capitalized
    • should be on the ENVIRONMENT section of torbrowser man page

Proof:

Run: env.
It will display the environment variables, which are capitalized can be reused by other scripts.

Shellscript portability:
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08

Environment variable names used by the utilities in the Shell and Utilities volume of POSIX.1-2017 consist solely of uppercase letters, digits, and the ( ‘_’ ) from the characters defined in Portable Character Set and do not begin with a digit. Other characters may be permitted by an implementation; applications shall tolerate the presence of such names. Uppercase and lowercase letters shall retain their unique identities and shall not be folded together. The name space of environment variable names containing lowercase letters is reserved for applications. Applications can define any environment variables with names from this name space without modifying the behavior of the standard utilities.

Other programming languages may use uppercase variables even when they are not environment variables, such as python and rust that use uppercase for constants.

What is missing from whonix

  • capitalize all environment variables
  • add to man page the use case of each environment variable
1 Like
2

Ok, the argument is convincing beyond doubt.

Confirmed.

Seems like a big task. Help welcome.

There’s a related developer helper script here. It does a Kicksecure and Whonix wide search and replace of any string anywhere in Whonix source code.

developer-meta-files/usr/bin/dm-replace-list at master ¡ Kicksecure/developer-meta-files ¡ GitHub

So any env vars that should be renamed could be added there.

  • left: search (old variable name)
  • right: replace (new variable name)

Then at some point, I’d run the script and do the project wide mass search / replace.

What’s missing is also automating the same change in the wiki.

Anyhow. Anyone can feel free to send mass search / replace suggestions (pull requests or git branches) to that script.

That would also be nice.

3

UWT_ variables are capitalized but not documented as there is no uwt man page.

1 Like
4

Normal variables shouldn’t be capitalized.

Whonix firewall scripts are using upper-case variables for normal variables.

Another reason of why their case needs to be distinct is to make the hierarchy obvious.
For example, if one variable is named gateway, its environment variable could still be named GATEWAY and it would be obvious their difference, because upper-case variables are variables exported to the environment.

export GATEWAY="sys-whonix-dev"

#!/bin/sh
# follow hierarchy:
# - command line
# - environment variable
# - default fallback value
gateway="${1:-"${GATEWAY:-"sys-whonix"}"}"
echo "${gateway}

this makes obvious that GATEWAY was exported to the environment and another variable can be used with the same name but lower case for defaults or assigned by other means.

1 Like
5

Ok.

How about global (non-environment) script wide variables?

6

The thing is, those variables are only used by firewall scripts.

Let’s take PATH for example, there is no problem in modifying PATH and adding ~/.local/bin to it by configuring it on the .bashrc, because PATH set in the .bashrc is user wide environment.

But the variables /etc/whonix_firewall.d are only for whonix firewall.

But in the end, you decide the approach but it has to be documented the standard to be followed, as it makes more clear what developers should use.

1 Like
7

I generally agree with you. For the next release upgrade, we could move to the more conventional style.

To clarify, at this stage, we don’t have any different opinions on this topic yet. Meaning, I am open to go with your suggestions. Just in case that previously came across differently.

So keep them lowercase?

I am not sure. In theory, whonix_firewall could be started from the command line with environment variables. Not sure that should be supported. An interesting use case would be firewall_mode.

What’s the convention for bash config snippets in /etc? /etc/default/grub uses uppercase variable names.

To improve my previous question: Lets say there was a script named debian-do-something by Debian (unspecific to Whonix) (asking general conventions here). How would global variables only valid in debian-do-something be stylized? Lowercase or uppercase?

8

I think env vars to set the firewall are not a good design because if calling as root, user need to remember to keepend

  • doas use keepenv in the doas.conf
  • sudo use -E, --keepenv

I think this can cause confusion.

I don’t think it would change but seeing some scripts on etc with upper-case, I believe the best is to set a whonix project policy for uniformity.

“Only valid to debian” → upper case

but for example, debian_chroot is not capitalized, so in the end, they also decide when to do so or not.

1 Like
9

The word “global variable” might be quite confusing. Just script wide:

  • local variables (bash keyword local)
  • global variables (bash default)

I am not referring to Debian / Linux wide variables such as PATH, TERM etc.

For “global” variables inside some standalone script. (grep -r bin/bash /usr/bin)

Which convention should be used? Probably not upper case unless that variable is documented as an environment variable?

sudo varname=content program

Then no -E / --keepenv required but indeed. Difficult to use and confusing. That’s more a thing for developers. Not something for user documentation.

1 Like