Project

xlat

0.0
The project is in a healthy, maintained state
xlatsorah/xlatHomepageDocumentationSource CodeBug TrackerWiki
Userland NAT64 implementation on Linux in Ruby
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
406
Stars
8
Forks
1
Watchers
1
 Releases
Current version
0.1.0.alpha1
Total releases
1
First release
2025-03-20
Latest release
2025-03-20
 Pull Requests
Open Pull Requests
2
Closed Pull Requests
2
Merged Pull Requests
39
Pull Request Acceptance Rate
90%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-03-23
Reverse Dependencies
0

 Dependencies

Runtime

rb_sys
~> 0.9.102
 Project Readme

Xlat

Userland NAT64 implementation on Linux in Ruby.

Supported usage

  • Stateless NAT64 - RFC 7915
    • Maps 1 IPv6 Address : 1 IPv4 Address
    • Combine with kernel netfilter NAT66 masquerade to archieve stateful NAT64 NAPT functionality (multiple IPv6 address/port : 1 IPv4 Address)
    • IPv6(src=nat66outer, dst=pref64n+ipv4) -> IPv4(src=ipv4nat64outer, dst=ipv4)
    • IPv4(src=ipv4, dst=ipv4nat64outer) -> IPv6(src=pref64n+ipv4, dst=nat66outer)

Installation

# Gemfile
source 'https://rubygems.org'
gem 'xlat'

Usage

TODO: Write usage instructions here

Caveats

  • Expecting no difference in IPv4 and IPv6 MTU
  • If an IPv4 packet is translated into an IPv6 packet larger than MTU, the packet is silently discarded.

Tips

Checksum Neutrality

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Benchmarking

Requires: iproute2, trafgen&ifpps from netsniff-ng (v0.6.8 of netsniff-ng has a bug and you need to build the development version).

The benchmark/ directory has trafgen scenarios to generate artificial traffic to benchmark Xlat.

sudo XLAT_PROFILE=1 XLAT_NOJIT=1 ruby ./benchmark/run.rb ./benchmark/tcp.cfg
# or if your ruby is managed by rbenv
sudo XLAT_PROFILE=1 XLAT_NOJIT=1 "$(rbenv which ruby)" ./benchmark/run.rb ./benchmark/tcp.cfg

If XLAT_PROFILE variable is set, profile is emitted every 10 seconds at /tmp/xlat-#{pid}.pf2profile. You need to disable YJIT by setting XLAT_NOJIT variable due to the current limitation of Pf2.

Profiling with Pf2 in Docker

Requires: Docker, containerlab, iproute2, iperf3.

cd clab/
./build
containerlab deploy --reconfigure
sudo ip netns exec clab-464xlat-ue-pd-sv iperf3 -s

# in another session:
sudo ip netns exec clab-464xlat-ue-pd-ue iperf3 -c 64:ff9b::192.0.2.80
docker kill --signal=USR1 clab-464xlat-ue-pd-plat
docker cp clab-464xlat-ue-pd-plat:/tmp/xlat-1.pf2profile .
pf2 report ./xlat-1.pf2profile -o ./xlat.json

Fuzzing

Requires: CRuby built with clang compiler.

fuzz/run performs fuzzing against the parsers and Xlat::Rfc7915 translator.

./fuzz/run

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/xlat.

License

The gem is available as open source under the terms of the MIT License.

Credits

  • Copyright (c) 2024 Sorah Fukumori
  • Copyright (c) 2024-2025 Kasumi Hanazuki
  • Copyright (c) 2022 Kazuho Oku