SYSCONS(4)

✨ NAME ✨

syscons, sc — the console driver 💖

---

✨ SYNOPSIS ✨

options MAXCONS=N
options SC_ALT_MOUSE_IMAGE
options SC_CUT_SEPCHARS=_characters_
options SC_CUT_SPACES2TABS
options SC_DISABLE_KDBKEY
options SC_DISABLE_REBOOT
options SC_HISTORY_SIZE=N
options SC_MOUSE_CHAR=C
options SC_NO_CUTPASTE
options SC_NO_FONT_LOADING
options SC_NO_HISTORY
options SC_NO_PALETTE_LOADING
options SC_NO_SUSPEND_VTYSWITCH
options SC_NO_SYSMOUSE
options SC_PIXEL_MODE
options SC_TWOBUTTON_MOUSE
options SC_NORM_ATTR=_attribute_
options SC_NORM_REV_ATTR=_attribute_
options SC_KERNEL_CONS_ATTR=_attribute_
options SC_KERNEL_CONS_ATTRS=_attributes_
options SC_KERNEL_CONS_REV_ATTR=_attribute_
options SC_DFLT_FONT
makeoptions SC_DFLT_FONT=_font_name_
device sc

In /boot/device.hints:
hint.sc.0.at="isa"
hint.sc.0.vesa_mode=0x103

In /boot/loader.conf:
kern.vty=sc

---

✨ DESCRIPTION ✨

so syscons gives you multiple virtual terminals — it's giving SCO color console driver energy. 💅

it's built on top of the keyboard driver atkbd(4) and the video card driver vga(4), so both need to be configured in your system, no cap.

only one syscons device can exist in the system, periodt.

🦋 Virtual Terminals 🦋

so it gives you multiple virtual terminals that look like separate terminals. one is the current one — it gets the screen and keyboard all to itself — and the others are just chilling in the background.

to actually use them, you gotta mark each one ``on'' in /etc/ttys so getty(8) knows they're active and runs login(1) so you can log in. by default, only the first eight virtual terminals are activated in /etc/ttys.

to switch, you press Alt plus a switch key. here's the mapping, bestie:

• Alt-F1 → ttyv0
• Alt-F7 → ttyv6
• Shift-Alt-F1 → ttyva
• Alt-F2 → ttyv1
• Alt-F8 → ttyv7
• Shift-Alt-F2 → ttyvb
• Alt-F3 → ttyv2
• Alt-F9 → ttyv8
• Shift-Alt-F3 → ttyvc
• Alt-F4 → ttyv3
• Alt-F10 → ttyv9
• Shift-Alt-F4 → ttyvd
• Alt-F5 → ttyv4
• Alt-F11 → ttyva
• Shift-Alt-F5 → ttyve
• Alt-F6 → ttyv5
• Alt-F12 → ttyvb
• Shift-Alt-F6 → ttyvf

you can also hit the ``nscr'' key (usually PrintScreen on the AT Enhanced keyboard) to cycle through virtual terminals. 🔄

default number of available virtual terminals is 16. you can change that with the kernel config option MAXCONS (see below).

note: the X server usually needs a virtual terminal for display, so at least one terminal has to be left unused by getty(8) so X can use it. don't forget! 💅

🦋 Key Definitions and Function Key Strings 🦋

so syscons plus the keyboard driver let you change key definitions and function key strings. the kbdcontrol(1) command loads a key definition file (aka a ``keymap'' file), dumps the current keymap, and assigns a string to a function key. check keyboard(4) and kbdmap(5) for the keymap file. 💖

you might wanna set the keymap variable in /etc/rc.conf.local to your desired keymap file so it auto-loads on startup. ✨

🎀 Software Font 🎀

for most modern video cards (like VGA), syscons and the video card driver let you change the screen font. use vidcontrol(1) to load a font file from /usr/share/syscons/fonts. 🎀

fonts come in 8x8, 8x14, and 8x16. the 8x16 is usually for VGA in 80-column-by-25-line mode. other video modes might need different sizes. bestie, it's better to always load all three sizes of the same font. 💅

you can set font8x8, font8x14, and font8x16 variables in /etc/rc.conf to the font files you want, and they'll auto-load on startup. 🌸

optionally, you can pick a particular font file as default. see the SC_DFLT_FONT option below. 👑

🦋 Screen Map 🦋

if your video card doesn't do software fonts, you might still get a similar vibe by re-mapping the font built into your card. use vidcontrol(1) to load a screen map file that defines the mapping between character codes. 🦋

🖱️ Mouse Support and Copy-and-Paste 🖱️

you can use your mouse to copy text on screen and paste it like you typed it by hand. you gotta be running the mouse daemon moused(8) and enable the mouse cursor in the virtual terminal via vidcontrol(1). 🖱️

press mouse button 1 (usually left) to start selecting. release button 1 to finish. selected text gets marked by inverting foreground and background colors. press button 3 (usually right) to extend the selection. the selected text goes into the copy buffer and you can paste it at the cursor by pressing button 2 (usually middle) as many times as you want. ✨

if your mouse only has two buttons, you might wanna use the SC_TWOBUTTON_MOUSE option below to make the right button paste. or you can make the mouse daemon emulate the middle button. check the moused(8) man page for more details. 💅

📜 Back Scrolling 📜

syscons lets you browse output that has ``scrolled off'' the top of the screen. 📜

press the slock'' key (usually <pink>ScrllLock / Scroll Lock</pink> or <pink>Pause</pink> on many keyboards) and you're in scrollback'' mode. the Scroll Lock LED shows it. use arrow keys, Page Up/Down, and Home/End to scroll through buffered output. press ``slock'' again to go back to normal mode. 🔄

the size of the scrollback buffer is set by the SC_HISTORY_SIZE option below. 💖

😴 Screen Saver 😴

syscons can put up the screen saver when the current virtual terminal is idle — meaning you're not typing or moving the mouse. see splash(4) and vidcontrol(1) for more. 😴✨

🎀 DRIVER CONFIGURATION 🎀

Okay bestie, this is the part where you actually get to customize the vibes. Two whole flavor categories: kernel config options (stuff you bake into the kernel itself) and driver flags (stuff you poke at boot). Let's go. 💅

✨ Kernel Configuration Options ✨

These are the little switches that control the syscons driver. Build-time decisions, no cap.

• MAXCONS=N — sets how many virtual terminals you get to N. Default is 16. Sixteen whole little screens, slay.
• SC_ALT_MOUSE_IMAGE — picks the alternative way of drawing the mouse cursor in the virtual terminal. Drawing that arrow-shaped cursor is lowkey expensive for some video cards, so you might wanna try this. BUT — and this is the tea — the alternative mouse cursor's appearance may not be very appealing. 🙈 Also important: if you use SC_NO_FONT_LOADING then you must also use this option if you want to be able to use the mouse at all.
• *SC_CUT_SEPCHARS=characters* — tells the driver which characters count as word boundaries when it's hunting for words during a cut operation. Default value is "\x20", which is literally just a space character. Iconic, minimal, a space.
• SC_CUT_SPACES2TABS — instructs the driver to convert leading spaces into tabs when copying data into the cut buffer. Genuinely useful if you want to preserve indentation while copying tab-indented text. Your indentation stays cute. ✨
• SC_DISABLE_KDBKEY — disables the ``debug'' key combination (by default that's Alt-Esc, or Ctl-PrintScreen). It stops users from entering the kernel debugger (KDB) by pressing that combo. Note: KDB will still be invoked when the kernel panics or hits a break point, if it's included in the kernel. If this option is not defined, you can control this behavior at runtime with the sysctl(8) variable hw.syscons.kbd_debug.
• SC_DISABLE_REBOOT — disables the ``reboot'' key (default: Ctl-Alt-Del) so the casual user can't accidentally reboot the whole system. 😭 If this option is not defined, runtime control lives in the sysctl(8) variable hw.syscons.kbd_reboot.
• SC_HISTORY_SIZE=N — sets the size of the back scroll buffer to N lines. Default is 100. Scrollback is self care.
• SC_MOUSE_CHAR=C — unless SC_ALT_MOUSE_IMAGE (above) is specified, the syscons driver reserves four consecutive character codes so it can display the mouse cursor in virtual terminals on some systems. This option sets the first character code to C. Default value is 0xd0. A good candidate is 0x03.
• SC_PIXEL_MODE — adds support for pixel (raster) mode console. Useful on some laptop computers, less so on most other systems, and it adds a substantial amount of code to syscons. If this option is NOT defined, you can reduce the kernel size a lot. See the VESAMODE flag below.
• SC_TWOBUTTON_MOUSE — if you have a two button mouse, you may want to add this so the right button pastes text. See “Mouse Support and Copy-and-Paste” above. 🖱️
• SC_NORM_ATTR= attribute
• SC_NORM_REV_ATTR= attribute
• SC_KERNEL_CONS_ATTR= attribute
• SC_KERNEL_CONS_ATTRS= attributes
• SC_KERNEL_CONS_REV_ATTR= attribute — these five set the default colors. Available colors are defined in <machine/pc/display.h>. See “EXAMPLES” below. Heads up: SC_KERNEL_CONS_ATTRS is a character string giving a sequence of attributes in binary format. The sequence will be repeated up to the number of CPUs. ⚠️ Beware that the string must not be null, since the kernel divides by its length. Do not do that to your kernel.
• SC_DFLT_FONT — specifies the default font. Available fonts are: iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865, cp866 and cp866u. 16-line, 14-line and 8-line font data will be compiled in. Without this option, the syscons driver will use whatever font is already loaded in the video card — unless you explicitly load a software font at startup. See “EXAMPLES” below.
• SC_NO_SUSPEND_VTYSWITCH — this one is also available as a loader(8) tunable and a sysctl(8) variable: hw.syscons.sc_no_suspend_vtswitch. It disables switching between virtual terminals (graphics <-> text) during suspend/resume (ACPI and APM). Use it if your system freezes when you're running X and trying to suspend. 💀

---

And now for the options that remove features from the syscons driver, saving you kernel memory. Trading features for RAM, the eternal struggle. 🫶

• SC_NO_CUTPASTE — disables the ``copy and paste'' operation in virtual terminals.
• SC_NO_FONT_LOADING — the syscons driver can load software fonts on some video cards; this option removes that feature. Note: if you still wish to use the mouse with this option, you must also use the SC_ALT_MOUSE_IMAGE option.
• SC_NO_HISTORY — disables back-scrolling in virtual terminals. 😔 No scrollback for you.
• SC_NO_SYSMOUSE — removes mouse support in the syscons driver entirely. The mouse daemon moused(8) will fail if this option is defined. This option implies the SC_NO_CUTPASTE option too.

🌈 Driver Flags 🌈

These driver flags can control the syscons driver. Set them with the hint.sc.0.flags tunable — either in /boot/device.hints, or else at the loader prompt (see loader(8)).

• 0x0080 (VESAMODE) — puts the video card in the VESA mode specified by the /boot/device.hints variable vesa_mode during kernel initialization. Note that for this flag to work, the kernel must be compiled with the SC_PIXEL_MODE option explained above. A list of the available mode can be obtained via vidcontrol(1).
• 0x0100 (AUTODETECT_KBD) — instructs the syscons driver to periodically scan for a keyboard device if it is not currently attached to one. Otherwise, the driver only probes for a keyboard once, during bootup.

🦋 Loader Tunables 🦋

Enter these at the loader(8) prompt or in loader.conf(5).

• kern.vty — when both syscons and vt(4) have been compiled into the kernel, you pick which one is used for the system console by setting this variable to 'sc' or 'vt'. The GENERIC kernel uses vt(4) when this value is not set. 👑

---

📁 FILES 📁

• /dev/console
• /dev/consolectl
• /dev/ttyv? — virtual terminals
• /etc/ttys — terminal initialization information
• /usr/share/syscons/fonts/* — font files
• /usr/share/syscons/keymaps/* — key map files
• /usr/share/syscons/scrmaps/* — screen map files

---

💖 EXAMPLES 💖

Since the syscons driver requires the keyboard driver and the video card driver, your kernel configuration file should contain the following lines:

device atkbdc
device atkbd
device vga
device sc
device splash

You also need these lines in /boot/device.hints for those drivers:

hint.atkbdc.0.at="isa"
hint.atkbdc.0.port="0x060"
hint.atkbd.0.at="atkbdc"
hint.atkbd.0.irq="1"
hint.vga.0.at="isa"
hint.sc.0.at="isa"

If you do not intend to load the splash image or use the screen saver, that last line is not necessary, and can be omitted.

Note that the keyboard controller driver atkbdc is required by the keyboard driver atkbd. They're a package deal, iykyk.

The following lines set the default colors. Normal text will be green on black background. Reversed text will be yellow on green background. ⚠️ Note that you cannot put any white space inside the quoted string, because of the current implementation of config(8).

options SC_NORM_ATTR=(FG_GREEN|BG_BLACK)
options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN)

The following lines set the default colors of the kernel message. The kernel message will be printed bright red on black background. The reversed message will be black on red background. 🔥

options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK)
options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED)

Provided SC_KERNEL_CONS_ATTR is not set, or is set to its default of bright white on black, the following line sets 4 red-ish colors for printing kernel messages in colors depending on the CPU:

options SC_KERNEL_CONS_ATTRS=\"\x0c\x04\x40\x0e\"

The default scheme is probably better for up to 8 CPUs. Use a long string to get unique colors for more than 8 CPUs. 🌈

To turn off all per-CPU coloring of kernel messages, set SC_KERNEL_CONS_ATTR to a non-default value, or use the default in a pattern of length 1:

options SC_KERNEL_CONS_ATTRS=\"\x0f\"

The following example adds the font files cp850-8x16.fnt, cp850-8x14.font and cp850-8x8.font to the kernel:

options SC_DFLT_FONT
makeoptions SC_DFLT_FONT=cp850
device sc

---

👀 SEE ALSO 👀

kbdcontrol(1), login(1), vidcontrol(1), atkbd(4), atkbdc(4), keyboard(4), screen(4), splash(4), ukbd(4), vga(4), vt(4), kbdmap(5), rc.conf(5), ttys(5), config(8), getty(8), kldload(8), moused(8)

---

📜 HISTORY 📜

The syscons driver first appeared in FreeBSD 1.0. A true OG. 👑

---

💜 AUTHORS 💜

The syscons driver was written by Søren Schmidt <sos@FreeBSD.org>. This manual page was written by Kazutaka Yokota <yokota@FreeBSD.org>. Legends, honestly.

---

⚠️ CAVEATS ⚠️

The amount of data that is possible to insert from the cut buffer is limited by the {MAX_INPUT}, a system limit on the number of bytes that may be stored in the terminal input queue — usually 1024 bytes (see termios(4)). So like, don't try to paste a whole novel. It's giving capped. 💀

---

🐛 BUGS 🐛

This manual page is incomplete and urgently needs revision. 😭 Not me telling on myself but okay, honesty is the vibe. If you find gaps, that's why.

---

That's a wrap bestie!! 🎀 This page came from the Debian version of the SYSCONS(4) manual, dated June 2, 2018. Go configure something iconic. 💖✨