Skip to content

Improve project organization #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DanielG wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Improve project organization #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0f2b25e
Split README in two: clatd(8) and README.md
DanielG Feb 21, 2025
c20a6f0
man: Rename BUGS section to REPORTING BUGS
DanielG Apr 6, 2025
8ecd339
Rewrite Makefile to be more idiomatic
DanielG Feb 21, 2025
dbbcbf8
mk: Fix Debian package list
DanielG Apr 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/clat.8
Copy link
Owner

@toreanderson toreanderson Feb 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surely this should be clatd.8 (or clatd.8.gz, see below)?

Copy link
Contributor Author

@DanielG DanielG Feb 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, typo.

77 changes: 57 additions & 20 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,66 @@
# clatd Makefile
#
# Copyright (C) 2025 Daniel Gröber <dxld@debian.org>
#
# SPDX-License-Identifier: MIT

DESTDIR=
PREFIX=/usr
SYSCONFDIR=/etc
BINDIR = $(PREFIX)/sbin

SYSTEMCTL = systemctl

CLATD = $(DESTDIR)$(BINDIR)/clatd
MANPAGE = $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8
SYSTEMD_SYSSERVICEDIR = $(DESTDIR)$(SYSCONFDIR)/systemd/system
NM_DISPATCHER = $(DESTDIR)$(SYSCONFDIR)/NetworkManager/dispatcher.d/50-clatd

Q = @

all: clatd.8
.ONESHELL:

APT_GET:=$(shell which apt-get)
DNF_OR_YUM:=$(shell which dnf || which yum)
SYSTEMCTL:=$(shell which systemctl)
TAYGA:=$(shell which tayga)
clatd.8: clatd.pod
pod2man \
--name clatd \
--center "clatd - CLAT, SIIT-DC and IPv6-only with many XLAT engines" \
--section 8 \
$< $@
Comment on lines +24 to +29
Copy link
Owner

@toreanderson toreanderson Feb 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any particular reason for no longer compressing the generated manual page? Most manual pages on my Fedora workstation are compressed with gzip, so I think that should be kept.

Copy link
Contributor Author

@DanielG DanielG Feb 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Compression is optional as far as man is concerned, it's usually handled by distros. Policy could vary, eg: should xz/lzma/gz be used and what compression settings, and recompressing to comply could be annoying for packagers depending on tooling. So it's just simpler for all involved not to do this upstream unless it's absolutely necessary for some reason. In general upstreams may eg. build tarballs to distribute themselves and size may be a concern there, but since that's not the case with clatd simplicity is the way to go IMO.

Looking at Fedora specifically it seems RPM handles the (re)compression. So removing the gz on the upstream side shouldn't impact them:

https://docs.fedoraproject.org/en-US/packaging-guidelines/#_manpages

When installing man pages, note that RPM will re-compress them into its preferred format. So the %files section MUST reference manpages with a pattern that takes this into account [...]

OpenSUSE on the other hand hardcodes the pod2man call to get an uncompressed file already:

https://build.opensuse.org/projects/openSUSE:Factory/packages/clatd/files/clatd.spec?expand=1

%build
pod2man --name clatd --center "clatd - a CLAT implementation for Linux" --section 8 README.pod clatd.8
sed -i "s,%{_sbindir}/clatd,%{_sbindir}/clatd -c %{_sysconfdir}/clatd.conf," scripts/*

Copy link
Owner

@toreanderson toreanderson Feb 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not entirely sure what you mean by «it's usually handled by distros». As an example, if I, on a Fedora machine drop an uncompressed manual page in /usr/share/man somewhere, there's no periodic job that ensures this file gets compressed, it will remain uncompressed forever. Compression should, the way I see it, be handled by the make install target (or any of its dependencies).

Copy link
Contributor Author

@DanielG DanielG Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tore. 99% of users are going to be using clatd throught their distros. What your plain make install target does only matters in so far as it works for development and doesn't make distro maintainer's life harder than it already is.

Distro maintainers and/or their build tooling will make the gz/xz/zstd'ing happen. In Debian's case most maintainers use the debhelper toolchain which has dh_compress to handle man page compression (if necessary) just before generating the .deb archive from $DESTDIR. It's complicated^TM ask for details at your own peril.

When was the last time you ran ./configure && make && make install in (for example) a iproute2 tarball unpack? :-)

Copy link
Owner

@toreanderson toreanderson Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read the manual page for dh_compress that you linked to. It says:

By default, dh_compress compresses files that Debian policy mandates should be compressed, namely all files in usr/share/info, usr/share/man, (…)

Ok, so it would compress the clatd manual page because it is installed to /usr/share/man/. Makes sense.

The manual page then goes on to say:

(…) (except (…) files that appear to be already compressed based on their extensions)

The current Makefile installs the manual page as clatd.8.gz, so it will appear to be already compressed based on its extension. Therefore, assuming dh_compress's manual page is to be trusted, it should be a no-op as far as the installed clatd.8.gz file is concerned.

I also noted the reference to Debian policy, and looked it up. The policy states:

Manual pages should be installed compressed using gzip -9.

As it happens, installing the manual page compressed with gzip -9 is precisely what the current Makefile does already.

So I do not understand what the actual problem is. As far as I can tell, what the current Makefile does already follows Debian policy to the letter, and does so in a way that the Debhelper build script is documented to deal with gracefully. Could you please explain the problem is, what is it that does not work for you exactly? Otherwise I'm inclined to say that if it ain't broke, don't fix it.

Copy link
Contributor Author

@DanielG DanielG Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tore. You're not looking at this with enough perspective. I've already given you all the information you need to figure out why this makes sense you're not seeing it.

Look at the amount of verbiage we've already spilled over this issue. The cost/benefit ratio is way out of whack here and I don't want to continue this discussion. Either you trust that I'm a distro person deeply versed in the issues (invisible to you) people downstream face or you don't.

If you see no actual problem with changing this why are we arguing about it? Are you just arguing to argue? I'd rather spend my time more productively than that.

I wasn't going to spell it out but I can't help myself: This will help OpenSUSE remove hardcoding from their build recipe and allow them to use the upstream Makefile instead (whithout any other distro feeling any impact due to tooling). This in turn reduces the amount of work they have to do as we introduce new binaries/manpages/features here.

A small thing but goes a long way to cultivating a positive relationship with your distributors, which is key to ubiquitous adoption of software in the Linux ecosystem.

--Daniel

Copy link
Owner

@toreanderson toreanderson Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have not heard a peep from the openSUSE packager about this issue, ever. As far as I know, their packages are working well. That said, if compressed manual pages are indeed a problem for them, I expect them to speak up for themselves.

Anyway. What could be done instead, is something like this:

COMPRESS_COMMAND = gzip -f9
…
	pod2man --name clatd --center "clatd - a CLAT implementation for Linux" --section 8 README.pod $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8 && $(COMPRESS_COMMAND) $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8 || echo "pod2man is required to generate manual page"

Or perhaps:

COMPRESS_MANPAGE = true
…
  pod2man --name clatd --center "clatd - a CLAT implementation for Linux" --section 8 README.pod $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8 || echo "pod2man is required to generate manual page"
  if $COMPRESS_MANPAGE; then gzip -f9 $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8; fi

This would allow the openSUSE maintainer to override COMPRESS_COMMAND (in much the same way PREFIX is) during package build to get an uncompressed manual page, while people that install from Git get a compressed manual page as before (which will also mean there will not be an outdated compressed manual page lingering on the system after upgrades).

Copy link

@gonsoos gonsoos Jun 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That said, if compressed manual pages are indeed a problem for them, I expect them to speak up for themselves.

Gentoo Linux compresses man pages themselves. The developer Sam wrote a succinct blog post about it:
https://cmpct.info/~sam/blog/posts/automatic-manpage-compression/

It'd be nice to keep compression optional, since we package the program:
https://gitweb.gentoo.org/repo/proj/guru.git/tree/net-misc/clatd?h=master


all:
clean:
-rm clatd.8

start: install
$(SYSTEMCTL) --system daemon-reload
$(SYSTEMCTL) --system -f --now enable clatd.service

stop:
$(SYSTEMCTL) --system disable --now clatd.service

uninstall: stop
-rm $(SYSTEMD_SYSSERVICE)/clatd.service \
$(SYSTEMD_SYSSERVICE)/clatd@.service \
$(NM_DISPATCHER)

install:
# Install the main script
install -D -m0755 clatd $(DESTDIR)$(PREFIX)/sbin/clatd
# Install manual page if pod2man is installed
pod2man --name clatd --center "clatd - a CLAT implementation for Linux" --section 8 README.pod $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8 && gzip -f9 $(DESTDIR)$(PREFIX)/share/man/man8/clatd.8 || echo "pod2man is required to generate manual page"
# Install systemd service file if applicable for this system
if test -x "$(SYSTEMCTL)" && test -d "$(DESTDIR)$(SYSCONFDIR)/systemd/system"; then install -m0644 scripts/clatd.systemd $(DESTDIR)$(SYSCONFDIR)/systemd/system/clatd.service && $(SYSTEMCTL) daemon-reload; fi
if test -e "$(DESTDIR)$(SYSCONFDIR)/systemd/system/clatd.service" && test ! -e "$(DESTDIR)$(SYSCONFDIR)/systemd/system/multi-user.target.wants/clatd.service"; then $(SYSTEMCTL) enable clatd.service; fi
# Install NetworkManager dispatcher script if applicable
if test -d $(DESTDIR)$(SYSCONFDIR)/NetworkManager/dispatcher.d; then install -m0755 scripts/clatd.networkmanager $(DESTDIR)$(SYSCONFDIR)/NetworkManager/dispatcher.d/50-clatd; fi
install -D -m0755 clatd $(CLATD)
install -D -m0644 clatd.8 $(MANPAGE)
install -D -m0644 scripts/*.service $(SYSTEMD_SYSSERVICEDIR)/
install -D -m0755 scripts/clatd.networkmanager $(NM_DISPATCHER)

DEB_PACKAGES = \
perl libnet-ip-perl libnet-dns-perl libjson-perl \
iproute2 nftables tayga

RPM_PACKAGES = \
perl perl-IPC-Cmd perl-Net-IP perl-Net-DNS perl-File-Temp perl-JSON \
iproute nftables

installdeps:
# .deb/apt-get based distros
if test -x "$(APT_GET)"; then $(APT_GET) -y install perl-base perl-modules libnet-ip-perl libnet-dns-perl libjson-perl iproute2 nftables tayga; fi
# .rpm/DNF/YUM-based distros
if test -x "$(DNF_OR_YUM)"; then $(DNF_OR_YUM) -y install perl perl-IPC-Cmd perl-Net-IP perl-Net-DNS perl-File-Temp perl-JSON iproute nftables; fi
# If necessary, try to install the TAYGA .rpm using dnf/yum. It is unfortunately not available in all .rpm based distros (in particular CentOS/RHEL).
if test -x "$(DNF_OR_YUM)" && test ! -x "$(TAYGA)"; then $(DNF_OR_YUM) -y install tayga || echo "ERROR: Failed to install TAYGA using dnf/yum, the package is probably not included in your distro. Try enabling the EPEL repo <URL: https://fedoraproject.org/wiki/EPEL> and try again, or install TAYGA <URL: http://www.litech.org/tayga> directly from source."; exit 1; fi
$(Q)prog_exists () { command -v $$@ >/dev/null 2>&1; }
{ PKGS='$(DEB_PACKAGES)'; PKG=apt; prog_exists $$PKG; } || \
{ PKGS='$(RPM_PACKAGES)'; PKG=dnf; prog_exists $$PKG; } || \
{ PKGS='$(RPM_PACKAGES)'; PKG=yum; prog_exists $$PKG; } || \
{ PKG=false; echo 'ERROR: Failed to detect system package manager.'>&2;}
$(DRY) $$PKG install -y $$PKGS
84 changes: 84 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# clatd - CLAT and SIIT-DC Edge Relay for Linux

**clatd** implements the CLAT component of the 464XLAT network architecture
specified in *RFC 6877*. It allows an IPv6-only host to have IPv4 connectivity
that is translated to IPv6 before being routed to an upstream PLAT (which is
typically a Stateful NAT64 operated by the ISP) and there translated back to
IPv4 before being routed to the IPv4 internet. This is especially useful when
local applications on the host requires actual IPv4 connectivity or cannot
make use of DNS64 (for example because they use legacy AF_INET socket calls,
or if they are simply not using DNS64).

**clatd** may also be used to implement an SIIT-DC Edge Relay as described in
*RFC 7756*. In this scenario, the PLAT is in reality a SIIT-DC Border Relay
(see *RFC 7755*) instead of a Stateful NAT64 (see *RFC 6146*). When used as a
SIIT-DC Edge Relay, you will probably want to manually configure the settings
`clat-v4-addr`, `clat-v6-addr`, and `plat-prefix` to mirror the SIIT-DC
Border Relay's configuration.

It relies either on the software package TAYGA by Nathan Lutchansky or on the
kernel module nat46 by Andrew Yourtchenko for the actual translation of packets
between IPv4 and IPv6 (*RFC 6145*) TAYGA may be downloaded from its home page
at <http://www.litech.org/tayga/>, nat46 from its repository at
<https://github.com/ayourtch/nat46>.

## Installing

clatd is available in the following distributions:

- [Arch (AUR)](https://aur.archlinux.org/packages/clatd-git)
- [Debian (sid)](https://packages.debian.org/search?keywords=clatd)
- [Fedora](https://packages.fedoraproject.org/pkgs/clatd/)
- [Nix](https://search.nixos.org/packages?show=clatd&type=packages&query=clatd)
- [OpenSUSE](https://software.opensuse.org/package/clatd)

Probably others also. If clatd is not available from your distribution or
you would like to test the bleeding-edge version of **clatd** from git use
the following commands:

$ git clone https://github.com/toreanderson/clatd
$ sudo make -C clatd installdeps start

This will install **clatd**, dependencies, systemd services, NetworkManager
dispatcher integration scripts on your system, enable and start the
clatd.service. Really only recommended for testing.
Copy link
Owner

@toreanderson toreanderson Feb 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why «Really only recommended for testing»?

make install is the supported way of installing clatd that should work anywhere. While users are of course free to use distro packages instead, they are often not available or outdated.

(Testing is better done by running clatd directly from the Git repo, there is no need to install it anywhere.)


Beware that TAYGA isn't available in all RPM-based distros (in particular
RHEL and its clones). It is however available in EPEL (see
<https://fedoraproject.org/wiki/EPEL>).


## Using

For extensive usage instruction please refer to the [clatd(8)](./clatd.pod)
manpage.

## Bugs

If you are experiencing any bugs or have any feature requests, head over to
<https://github.com/toreanderson/clatd/issues> and submit a new issue (if
someone else hasn't already done so). Please make sure to include logs with
full debugging output (using `-d -d` on the command line or `debug=2` in
the configuration file) when reporting a bug.

## License

Copyright (c) 2014-2025 Tore Anderson <tore@fud.no>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
43 changes: 4 additions & 39 deletions README.pod → clatd.pod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,25 +74,6 @@ exit gracefully.
See the I<scripts/> directory in the source distribution for some examples on
how to invoke it it.

=head1 INSTALLATION

The following commands will quickly download and install the latest version
of B<clatd> and its dependencies:

=over

=item git clone https://github.com/toreanderson/clatd

=item sudo make -C clatd install installdeps

=back

This will install B<clatd> to /usr/sbin, plus install systemd, and/or
NetworkManager scripts if your distribution appears to be using them, and
install all the dependencies. Note that TAYGA isn't available in all RPM-based
distros (in particular RHEL and its clones). It is however available in EPEL
(see L<https://fedoraproject.org/wiki/EPEL>).

=head1 CONFIGURATION

B<clatd> is designed to be able to run without any user-supplied configuration
Expand Down Expand Up @@ -476,35 +457,19 @@ not carry a prefix length.
B<clatd> will not attempt to perform a connectivity check to a discovered PLAT
prefix before setting up the CLAT, as I<RFC 7050> suggest it should.

=head1 BUGS
=head1 REPORTING BUGS

If you are experiencing any bugs or have any feature requests, head over to
L<https://github.com/toreanderson/clatd/issues> and submit a new issue (if
someone else hasn't already done so). Please make sure to include logs with
full debugging output (using I<-d -d> on the command line or B<debug=2> in the
configuration file) when reporting a bug.

=head1 LICENCE

Copyright (c) 2014-2025 Tore Anderson <tore@fud.no>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
=head1 COPYRIGHT

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
Copyright (c) 2014-2025 Tore Anderson <tore@fud.no>.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
SPDX-License-Identifier: MIT

=head1 SEE ALSO

Expand Down