OSCam oscam.server Configuration File Explained for Beginners (2026)

If you've gotten OScam compiled and running, the web interface loads fine on port 8888, and then you open oscam.server and just stare at it — you're not alone. This is the oscam oscam.server configuration file explained for beginners, written for the exact moment you're in right now: readers showing OFF or CONNECTED-but-not-decoding, a block you copied from a forum thread that "should" work, and no idea which lines actually matter versus which ones OScam is quietly ignoring.

I've rebuilt this file from scratch more times than I'd like to admit, on everything from a Raspberry Pi running a source build to Enigma2 boxes with their weird symlinked config folders. The good news: once you understand what each line is actually for, oscam.server stops being magic. This guide walks through the file line by line, shows three fully worked reader blocks, and — this is the part most guides skip — teaches you how to read the reader status column so you can diagnose your own setup instead of guessing.

What oscam.server Actually Does (And What It Doesn't)

The single biggest misconception I see from people new to OScam is treating oscam.server as "the config file." It's not. OScam splits its configuration across three files, and each one has a specific job. Mixing them up is why half the setup guides out there confuse people — they'll tell you to add a port number to oscam.server, and it just sits there doing nothing because ports don't live there.

Where the file lives

On a source build, it's usually /usr/local/etc/oscam.server. On Enigma2/Dreambox receivers it's typically /etc/tuxbox/config/oscam.server, though some images stash it under /var/keys/. Don't guess — check the OScam web interface status page, which shows the ConfigDir OScam is actually using. If you started OScam with the -c flag (for example, oscam -c /etc/oscam/), that path overrides everything else, including any file sitting in the default location.

The one-sentence rule

oscam.server defines sources of decryption. oscam.user defines consumers of decryption. If you remember nothing else from this article, remember that. Every time you're tempted to add something to oscam.server that sounds like it's about "who can use my server," stop — that's oscam.user's job.

How a reader block maps to something real

Each [reader] block in oscam.server corresponds to exactly one thing: a physical smartcard sitting in a USB reader, one network peer you're pulling keys from, or a local emulator like CCcam-emu or Newcamd-emu. It's a 1:1 mapping. If you have two physical cards, you need two reader blocks. If you have one CCcam line, that's one block.

Reading the file OScam actually loaded

Here's the part that trips people up constantly: OScam parses oscam.server at startup and again when you hit Restart from the web UI — not when you save a text file over SSH. If there's a syntax error in a block, or a duplicate label, OScam doesn't throw a dialog box or write a loud error. It just silently drops that block. The reader simply won't exist. Always go to Config > Reader in the web UI after a restart and confirm the reader name you typed is actually listed. If it's missing, the block never parsed — full stop, don't waste time troubleshooting the network for a reader that OScam never loaded.

Anatomy of a Reader Block: Every Line, What It Does, When to Omit It

This is the part everyone actually needs, so let's build it up from nothing. Here's a minimal working newcamd reader block — six lines, nothing fancy:

[reader]label = myreader1protocol = newcamddevice = server.example.net,12000user = myusernamepassword = mypasswordkey = 0102030405060708091011121314

That's genuinely enough to get a newcamd reader connecting. Now here's a fuller block with the parameters people actually argue about on forums:

[reader]label = myreader1enable = 1protocol = newcamddevice = server.example.net,12000user = myusernamepassword = mypasswordkey = 0102030405060708091011121314caid = 1802group = 1inactivitytimeout = 30reconnecttimeout = 15lb_weight = 100

Now let's go through what each line actually does, and — more importantly — when it's safe to leave out.

label

The internal name for this reader. It shows up in the web UI, in your logs, and it's what oscam.user references indirectly through group numbers. It has to be unique across the whole file — duplicate labels cause one block to silently overwrite or get dropped, and the symptom is a reader that's just missing from the Readers tab with no explanation. Keep it short, no spaces if you can avoid it, and something you'll recognize six months from now.

protocol

Tells OScam what kind of source this is: cccam, camd35, cs378x, newcamd, internal (for local emulation), or mouse / smartreader for a physical card in a USB reader. This line is mandatory and it has to match what's actually on the other end — a cccam server won't answer a newcamd handshake no matter how correct the rest of your block is.

device

This one line means two completely different things depending on protocol. For a physical card it's a serial path like /dev/ttyUSB0 or /dev/sci0. For any network protocol (newcamd, cccam, camd35, cs378x) it's host,port — for example server.example.net,12000. Mixing these up is a classic copy-paste mistake: pasting a serial device path into a network reader block, or vice versa, does nothing but produce a reader stuck in a connecting loop.

user / password

Credentials for logging into the remote source. These come from whoever runs that source — they are not your OScam web UI login, and they're not the credentials in your oscam.user file either. Three separate credential sets, three separate purposes. Confusing these is extremely common and produces an instant login rejection.

group

This is the single most misunderstood line in the entire file, and it's the direct link between oscam.server and oscam.user. group is a comma-separated list of integers — group = 1 or group = 1,3,7. A reader in group 1 will only ever serve clients whose group line in oscam.user also includes 1. If your reader is group=2 and your test client is group=1, the reader can be fully CONNECTED and healthy and your client will get exactly zero ECMs from it, forever. This mismatch is the number one cause of "reader is connected but nothing decodes," and it's rarely explained properly anywhere else.

caid, ident, chid, boxid

Think of these as whitelist filters. Leave them blank and OScam asks the reader for whatever CAIDs the reader itself reports having. Fill in caid = 1802 and you're telling OScam "only ever ask this reader about CAID 1802" — everything else gets ignored even if the reader technically has it. This is useful for trimming wasted ECM traffic and keeping load balancing sane, but a typo'd CAID value produces a reader that connects fine and just never receives a single ECM request, which looks exactly like a network problem but isn't. ident narrows further to specific provider IDs within a CAID, chid to specific channel IDs, and boxid ties a network reader to a specific box identifier some providers require. Leave all of these empty when you're first getting a reader working, then narrow them once it's confirmed functional.

cccversion, cccmaxhops, ccckeepalive, cccwantemu

These only apply to protocol=cccam and OScam ignores them entirely for every other protocol. cccversion sets the CCcam protocol version string your reader announces (2.3.0 is common). cccmaxhops caps how many links away a card can be and still count — more on this in the worked example below. ccckeepalive keeps the TCP session alive with periodic pings so it doesn't silently time out. cccwantemu tells the peer whether you're willing to accept emulated (non-card) sources through that link.

inactivitytimeout, reconnecttimeout, lb_weight, fallback, disablecrccws

The tuning lines. inactivitytimeout (seconds) drops and reconnects a reader that's gone quiet — useful for flaky network sources. reconnecttimeout controls the delay before retrying a failed connection; bump this up if your box's network takes a while to come online after boot. lb_weight influences how OScam's load balancer prioritizes this reader against others serving the same CAID — higher weight means it gets picked more often, assuming your load balancing is enabled in oscam.conf. fallback = 1 marks a reader as a last resort, only used if your primary readers can't answer. disablecrccws suppresses a specific CRC-based card-swap detection some setups don't need.

Parameters that only apply to physical cards

mhz and cardmhz set the clock speed OScam uses to talk to a physical smartcard — typical values are 357/357 or 600/357 depending on the card and reader hardware. detect controls how OScam senses card insertion/removal on some reader hardware. readnano is for specific card types that need extra ATR handling. None of these do anything on a network protocol. I still see forum-posted cccam and newcamd blocks with mhz=368 sitting in them — it's harmless, but it's dead weight, and it tells you the person who wrote the post didn't fully understand what they were pasting either.

Three Reader Blocks, Fully Worked

Theory's fine, but you came here to write a working block. Here are three, covering the setups people actually run.

A local smartcard in a USB reader

First, find the actual device path — don't guess. Run dmesg | grep tty right after plugging the reader in, or check ls /dev/serial/by-id/ for a persistent name that survives reboots (USB enumeration order can shift /dev/ttyUSB0 to /dev/ttyUSB1 after a reboot, which will silently break a hardcoded path).

[reader]label = localcard1enable = 1protocol = mousedevice = /dev/ttyUSB0mhz = 357cardmhz = 357group = 1detect = CD

Some phoenix-style readers use /dev/sci0 instead, and older serial-port readers show up as /dev/ttyS0. If the card is detected but you're getting intermittent NEEDINIT, that's very often the mhz/cardmhz pair, not a network or config problem — try 600/357 before you assume the card or reader is faulty.

A network reader over newcamd

[reader]label = netreader_newcamdenable = 1protocol = newcamddevice = server.example.net,12000user = myusernamepassword = mypasswordkey = 0102030405060708091011121314caid = 1802group = 1inactivitytimeout = 30

The key line is a 14-byte DES key given to you by whoever runs the source — it's not something you make up. Note that caid is set explicitly here rather than left blank; that's not optional convention, it's because the newcamd protocol generally carries one CAID per port, so the source expects you to declare which one you're connecting for.

A network reader over cccam

[reader]label = netreader_cccamenable = 1protocol = cccamdevice = server.example.net,12000user = myusernamepassword = mypasswordcccversion = 2.3.0cccmaxhops = 2ccckeepalive = 1group = 1

cccmaxhops = 2 means you'll accept cards up to two links away: hop 1 is the peer's own local card, hop 2 is a card that peer is itself sharing from someone else. Raising this to 5 doesn't magically produce more cards — it only widens what you're willing to accept from further down the chain, and distant cards tend to mean slower, less reliable ECM responses. Start at 1 or 2. If your ECM times are bad, lower the number rather than raise it.

A cs378x reader between two OScam boxes on your LAN

If you're linking two OScam installs you control, use cs378x instead of camd35 — it's encrypted, costs you nothing in performance, and there's no reason to run the unencrypted variant on your own network in 2026.

[reader]label = lan_upstreamenable = 1protocol = cs378xdevice = 192.168.1.50,17000user = lanclientpassword = lanpasswordgroup = 2

And the matching side on the upstream box's oscam.user, so you can see the group pairing end to end:

[account]user = lanclientpwd = lanpasswordgroup = 2au = 1

Notice group = 2 appears on both sides. That's the whole trick — without that match, the connection can succeed at the TCP/login level and still never pass a single key.

Reading Reader Status: What CONNECTED, OFF and NEEDINIT Are Telling You

This is where the config file stops being abstract and starts being debuggable. The status column in the web UI Readers tab is a diagnostic instrument if you know how to read it.

OFF

Either enable=0 is set in the block, or — far more often for beginners — the block never parsed at all. Go back and confirm the reader actually appears with the label you expect. If it's flat-out missing, you have a syntax error or duplicate label, not a connectivity problem.

CONNECTING or NEEDINIT, looping

The block parsed, but the handshake isn't completing. This is almost always wrong port, wrong protocol keyword, or bad credentials. Double-check device= against protocol= — a newcamd device line pointed at a cccam port will loop here forever.

CONNECTED, but zero ECMs sent

This is the "connected but not decoding" case everyone hits eventually. CONNECTED only confirms the TCP session and login succeeded — it says nothing about whether the reader is actually being asked for anything. Check, in order: does the reader's group value appear in your client's group line in oscam.user, is a caid/ident line silently filtering out the channel you're testing, and does the reader's card list actually contain that CAID/provider at all.

CONNECTED, ECMs sent, all "not found"

Different problem entirely — this means the request is reaching the reader correctly and it's answering honestly that it doesn't have that particular key. At that point the source genuinely lacks the CAID or provider you're testing; no config change on your end fixes that.

Tail your log with something like tail -f /tmp/oscam.log | grep myreader1 (log location itself comes from logfile= in oscam.conf, not oscam.server) and watch the sent / found / not found / timeout counters on the reader as you tune into a channel. A sent counter that never moves means the request never left your box — that's a routing/group/filter problem. A sent counter that climbs while found stays at zero means the source doesn't have it. Two completely different fixes, and the counters are the only thing that tells them apart.

Editing Safely: Syntax Rules, Reloads and Backups

A few habits will save you real time here. Comments start with #, and on some builds an inline comment after a value on the same line isn't honored — put comments on their own line to be safe. Whitespace and case matter more than people expect: protocol=cccam works everywhere, but protocol = cccam with spaces around the equals sign fails to parse on some older builds. When in doubt, drop the spaces.

Restart re-reads the entire config from disk, including oscam.server. Reload (where available) is lighter and re-reads a narrower set of settings — when you're not sure which one picked up your change, use Restart and check the Readers tab.

Here's the one that burns people: the OScam web interface, when you save any config page, can rewrite oscam.server from its own in-memory model. That rewrite strips comments and drops any parameter your particular build doesn't recognize. So keep a backup outside the config directory — cp oscam.server oscam.server.bak — before you touch anything in the web editor. If you rely on comments to remember what a block does, edit over SSH instead of through the Files tab.

On Enigma2/Dreambox images specifically, watch for symlinked or read-only config directories. Edits through the web UI can appear to save fine and then revert after a reboot because the real file OScam reads lives somewhere else — /etc/tuxbox/config versus /usr/keys is a common mismatch on these images. Check the ConfigDir on the status page again if changes aren't sticking.

Last thing: not every parameter exists in every OScam build. Run oscam -V to see your build info, and check the readme that shipped with your specific source rather than trusting a parameter you found in a five-year-old forum post. Unknown parameters aren't rejected loudly — they're usually just ignored, which is exactly why copy-pasted blocks with extra lines "work" while those extra lines do absolutely nothing.

Choosing a Reader Source Without Getting Burned

Worth being direct about this: OScam's legitimate purpose is letting someone with a valid subscription card use it across their own devices on their own network — reading your own card from a headless box in a closet instead of leaving a receiver plugged directly into the TV. Sharing a subscription outside your own household is against the terms of virtually every provider and is illegal in a lot of jurisdictions. This guide is about understanding the configuration file, not about getting access you're not entitled to.

If you are evaluating a network reader source for your own lawful subscription, judge it on measurable things rather than promises. Reasonable ECM response time is well under a second on a healthy link — if you're seeing multiple seconds consistently, something's wrong upstream. Hop count matters, as covered above: a source insisting on cccmaxhops of 5 or more to "get everything" is asking you to accept distant, unreliable cards rather than fixing their own setup. CAID coverage should be specific and checkable, not a vague "everything" claim.

Red flags worth walking away from: a CAID list that's unrealistically broad for what should be one or two subscription cards, no willingness to let you test before committing to anything, or any pressure to disable logging or hide what you're connecting to. And never reuse the same username and password across multiple sources — treat each set of reader credentials as its own isolated login, the same way you'd treat any other account.