LYREBIRD(1)

👑 LYREBIRD(1) — the pluggable transport proxy, bestie edition

okay so welcome to the lyrebird manual page, section 1 of the General Commands Manual 🦋 this is the whole thing, every last flag, no skips, no cuts, we're doing this properly ✨

---

🌸 NAME

lyrebird — a pluggable transport proxy for Tor that implements obfs4 💅

---

✨ SYNOPSIS

lyrebird [options]

that's it, that's the whole vibe check 🎀 no subcommands, no drama, just options.

---

💖 DESCRIPTION

so like. lyrebird is a tool that attempts to circumvent censorship by transforming the Tor traffic going between the client and the bridge 🌈 the way it works is that censors are usually monitoring that client↔bridge traffic, and instead of seeing actual Tor traffic they see innocent-looking transformed traffic. like a disguise. a little costume. iconic behavior honestly 👑

lyrebird implements these obfuscation protocols, and yes we're listing all of them:

• obfs2
• obfs3
• ScrambleSuit — client only, sorry servers 🫶
• meek — also client only 😭
• obfs4

and listen: lyrebird is currently only supported as a managed pluggable transport, spawned as a helper process via the tor daemon. that's the whole deployment story, no cap.

---

🔥 OPTIONS

• -h, --help — shows you the usage info and then dips. exit stage left 💅
• --version — shows you the version info and exits. that's the whole job ✨
• --enableLogging — turns logging on 📝
• --logLevel=level — sets the max log severity that actually gets logged out of "ERROR", "WARN", "INFO", and "DEBUG". pick your chaos level 🎚️
• --unsafeLogging — disables the IP address scrubber when logging, which means personally identifiable information ends up stored in the logs 😭 be so serious before you turn this on bestie
• --obfs4-distBias — when it's generating probability distributions for the obfs4 length and timing obfuscation, this makes it generate biased distributions similar to ScrambleSuit 🎲

---

🌿 ENVIORNMENT

yes it's spelled "ENVIORNMENT" in the original, I'm not touching it, I'm just the messenger 🙈

lyrebird honors all of the enviornment variables as specified in the Tor Pluggable Transport Specification 💚 (again, their spelling, not mine ✨)

---

🎀 FILES

• DataDirectory/pt_state/lyrebird.log — the log file. assuming logging is enabled, so like, --enableLogging bestie 📄
• DataDirectory/pt_state/obfs4_state.json — the Bridge (server) auto-generated obfs4 bridge parameters file 🗂️ this file will not be created if the administrator specifies them in the torrc via a ServerTransportOptions directive. so either you let it cook or you do it yourself 💅
• DataDirectory/pt_state/obfs4_bridgeline.txt — the Bridge (server) obfs4 bridge's client parameters 🦋 this file gets created and it contains the Bridge directive that a client should add to their torrc to connect to the running server's obfs4 instance. it's literally the lil note that says "hey, here's how to find me" 💌

---

📜 CONFORMING TO

Tor Pluggable Transport Specification ✨

---

⭐ NOTES

• using the obfs4 protocol requires tor-0.2.5.x or later, no exceptions 🕰️
• the obfs2 protocol is included for backwards compatibility purposes only, and should not be used in new deployments. it's giving legacy. it's giving "we keep it around for the elders" 🙈

---

🧚 EXAMPLE

As a client — to configure tor so it can use obfs4 bridges, add lyrebird to the torrc like thus:

# Use lyrebird to provide the obfs4 protocol.
ClientTransportPlugin obfs4 exec /usr/bin/lyrebird

As a server — to configure tor to act as an obfs4 bridge, add lyrebird to the torrc like thus:

#
# In addition to the standard tor bridge configuration, add:
#

# Use lyrebird to provide the obfs4 protocol.
ServerTransportPlugin obfs4 exec /usr/bin/lyrebird

look at those comments, they're doing so much heavy lifting 🌸

---

🌈 SEE ALSO

tor (1), torrc (5), obfsproxy (1), obfs4proxy (1) 💜

---

and that's the whole page babes 🫶 this one's from 2015-10-29, part of the General Commands Manual — go forth and obfuscate responsibly, mwah 💅✨