aboutsummaryrefslogtreecommitdiff
path: root/index.org
blob: 9c35b07f559c245e13a04696d5826fd9e48d5924 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
* Overview

*Xenv* is a text preprocessor that expands references to environment
variables in the input text to their actual values.  Environment 
variables are referenced using POSIX-compatible shell syntax.
Text is read from the standard input and expanded text goes to the
standard output.

* Rationale

It became a de-facto practice to configure docker containers using 
environment variables.  The method is obvious when configuration
is consumed by some programming language (*php*, *python* or the
like).  However, sometimes the need arises to expand environment
variables in configuration files of the utilities that provide no
mechanism for this (such as *mysqld* or *ldap*, for instance).

I often use [[http://puszcza.gnu.org.ua/software/pies/][GNU pies]] as entrypoint for images I produce.  It uses
[[https://www.gnu.org/software/m4][m4]] for preprocessing its configuration.  Several mechanisms have
been proposed for expanding environment variables in it: implementing
special
[[http://puszcza.gnu.org.ua/software/pies/manual/Docker-Entrypoint.html][macros]] or a [[http://git.gnu.org.ua/cgit/gsc/m4env.git/][wrapper program]].  However, the shortcomings of both 
became apparent and the need of something more convenient motivated 
the inception of this utility.

* Variable references

The input text can reference the environment variables using the
following constructs:

- $ _variable_

  The value of _variable_ is substituted.

- ${ _variable_ }

  The value of _variable_ is substituted.

- ${ _variable_ :- _word_ }

  If _variable_ is unset or null, the expansion of _word_ is substituted.
  Otherwise, the value of _variable_ is substituted.

- ${ _variable_ := _word_ }

  If _variable_ is unset or null, the expansion of _word_ is
  assigned to _variable_.  The value of _variable_ is then substituted.

- ${ _variable_ :? _word_ }

  If _variable_ is null or unset, the expansion of _word_ (or a
  message to that effect if word is not present) is output to standard error.
  Otherwise, the value of _variable_ is substituted.

- ${ _variable_ :+ _word_ }

  If _variable_ is null or unset, nothing is substituted, otherwise the
  expansion of _word_ is substituted.

- ${ _variable_ :| _word1_ | _word2_ }

  Unless _variable_ is null or unset, substitues the expansion of
  _word1_, otherwise the expansion of _word2_.

In the constructs above the colon can be omitted, resulting in a test
only for a variable that is unset.

The _indirection operator_ *$* can be changed to another symbol using 
the command line option *-S*.

* Documentation

The documentaion for *xenv* is [[http://man.gnu.org.ua/manpage/?1+xenv][available online]].

* Downloads

Download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz][latest version]] of *xenv*.

The tarball is signed using the author's GPG key.  To verify it,
import the author's key using the following command:

#+BEGIN_SRC shell-script
gpg --keyserver keys.gnupg.net --recv-keys 3602B07F55D0C732
#+END_SRC

Then, download the [[https://download.gnu.org.ua/release/xenv/xenv-1.1.tar.gz.sig][signature]] file and run

#+BEGIN_SRC shell-script
gpg --verify xenv-1.1.tar.gz
#+END_SRC

Checksums for this tarball are [[https://puszcza.gnu.org.ua/forum/forum.php?forum_id=1270][listed here]].

This and other versions of the utility can be downloaded from
https://download.gnu.org.ua/release/xenv (the *ftp* protocol
is also supported).

** Other references:

- [[https://puszcza.gnu.org.ua/projects/xenv][Project development page]]

- [[http://git.gnu.org.ua/cgit/xenv.git][Git repository]]

* Bug reports

If you think you found a bug in *xenv* or in its documentation, please 
send a mail to [[mailto:gray@gnu.org][Sergey Poznyakoff]] or use the web [[https://puszcza.gnu.org.ua/bugs/?group=xenv][bug tracker]].

* Copyright

Copyright (C) 2021 Sergey Poznyakoff

Permission is granted to anyone to make or distribute verbatim copies
of this document as received, in any medium, provided that the
copyright notice and this permission notice are preserved,
thus giving the recipient permission to redistribute in turn.

Permission is granted to distribute modified versions
of this document, or of portions of it,
under the above conditions, provided also that they
carry prominent notices stating who last changed them.

* Document settings :noexport:

Please ignore this section. It supplies the variables necessary for
proper rendering of this document.

:PROPERTIES:
:VISIBILITY: folded
:END:

#+TITLE: xenv
#+STARTUP: showall
#+EXCLUDE_TAGS: noexport
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
#+OPTIONS: ^:nil

# Local Variables:
# mode: org
# paragraph-separate: "[ 	^L]*$"
# version-control: never
# End:

Return to:

Send suggestions and report system problems to the System administrator.