===== dCore Basic Usage Guide =====

==== Overview ====
A basic dCore usage guide for new users. Prior Tiny Core Linux experience is helpful but not necessary. As it is often best to learn by doing, experiment with a [[http://wiki.tinycorelinux.net/dcore:installations|dCore Base Installation]] while reviewing this documentation.

As both Tiny Core Linux and dCore share a similar base, the [[http://tinycorelinux.net/book.html|Into the Core book]] (PDF format) is a good starting point for Tiny Core Linux concepts. There are, however, differences between these systems, the most significant being package management. Tiny Core Linux retrieves pre-compiled binary packages (*.tcz extensions) from it's own repository via Apps (GUI) or tce-ab (CLI, command line interface). While dCore creates [[http://wiki.tinycorelinux.net/dcore:handling_extensions|SCEs]] (*.sce, Self Contained Extensions) from imported Debian/Ubuntu repository packages (*.deb files) and uses sce-* commands to manage extensions, see [[http://wiki.tinycorelinux.net/dcore:extensions|dCore Extension Management]].

The most basic dCore system requires two files totaling <20 MB, a minimal kernel (eg. <4MB vmlinuz-stretch) and the compressed base file system (eg. <16 MB dCore-stretch.gz). A persistent installation also requires drive space to set up the TCE (Tiny Core Extension) directory. The TCE directory is typically set up by booting the base system and running the ''tce-setdrive'' command or by designating a TCE partition via a boot loader 'tce' [[http://distro.ibiblio.org/tinycorelinux/faq.html#bootcodes|boot code]] (eg. tce=sda2). A designated partition can be utilized or even an existing Linux partition, which creates a /tce/ directory in the partition's root directory. From a networked dCore boot run [[http://wiki.tinycorelinux.net/dcore:readme.sh_command|readme.sh]] and review README-1st.txt and other important [[http://tinycorelinux.net/dCore/x86/README/|READMEs]].

A base install initially boots dCore into TTY only, which provides //vi// as the default text editor. Installing graphics provides the graphic //fltk-editor//. Installing from a dCorePlus ISO provides a quick-start basic graphic system. Review the [[http://wiki.tinycorelinux.net/dcore:faq#basic_installation|basic installation FAQ]] and associated links for more information.

As a basic installation is minimal, the system can then be expanded and fully customized with kernel modules, drivers, Xorg graphics, various Window Managers or Desktop Environments, sound and any other desired software. As dCore imports software directly from pre-compiled Debian/Ubuntu repositories, thousands of packages are available. Additional software is also available from the dCore pre-built repository, such as kernel modules and select lightweight software no longer available from Debian/Ubuntu.

This guide uses a typical persistent installation that requires using the ''backup'' command to save session changes in /home/, /opt/ and other directories. Additional boot codes (linked above), such as home=sda1 and opt=sda1, can also be used for systems set up with these dedicated partitions.

Although classic, vi is often considered less than user friendly. It is, however, an efficient command line editor that is quite simple to use once a few keyboard commands have been memorized, there are several tutorials online. Regardless, users that wish to use a more user friendly CLI-based editor could import and load ''nano'', provided the dCore install has a working network connection:
<code>
sce-import -b nano # Import nano, add to sceboot.lst so it's always available
sce-load nano      # Load nano for use during this session (not required on reboot)
nano file_name     # Open file with nano, prepend sudo for root owned files
                   # The ^ command key (eg. ^X to exit) denotes the Ctrl key 
</code>

Congratulations, already imported and loaded your first extension!

==== Basic GUI Management ====
Supported [[http://wiki.tinycorelinux.net/dcore:x-desktop#dcore_window_managers_and_desktop_environments|Window Managers]] provide user friendly graphic tools from the main menu. Depending on the Window Manager, the main menu can be opened and explored by either selecting the dCore 'menu' button, middle or right-clicking desktop free space or a window's title bar.

Main menu items:
  * OnDemand: Quick load SCEs imported via OnDemand during run time, most applications with desktop files will also auto-launch.
  * System Tools: Quick launch [[http://wiki.tinycorelinux.net/dcore:sce-import_command|sce-import]] in a terminal to import Debian/Ubuntu packages, open FLTK-editor, run program box, take a screenshot, view top process monitor or Xkill a graphic application.
  * System Tools -> Control Panel: Quick launch for Backup/Restore, Date/Time, Network, wbar configuration, Mount Tool, Mouse Tool, System Stats, Wallpaper, Services, Swapfile Tool, Terminal Server and SCE Tools.
  * System Tools -> Control Panel -> SCE Tools: Quick launch the most commonly used [[http://wiki.tinycorelinux.net/dcore:extensions#dcore_sce_management_commands|dCore SCE Management Commands]] with default options via terminal popup (sce-import, sce-load, sce-debpurge, sce-update, sce-remove).
  * Exit: Exit system, includes options to shutdown, reboot or exit to prompt (TTY), perform a regular backup, safe backup or no backup.

==== Basic CLI Management ====
Traditionally dCore is managed primarily by command line and it is possible to perform all necessary tasks via CLI if desired. Once familiar with dCore operation, many users will likely prefer this method or use a combination of CLI and graphic tools. As the [[http://wiki.tinycorelinux.net/dcore:extensions#dcore_sce_management_commands|dCore SCE Management Commands]] are feature rich, advanced users will appreciate performing these tasks from command line. Note, a default dCore installation uses the ''sudo'' command, not ''su'', and does not require a user or sudo password. User name and passwords can, however, be modified as desired.

Tab autocomplete is supported. In a terminal, press the tab key twice to list all presently available system commands. As SCEs are loaded for use, via sceboot.lst, ''sce-load'' command or OnDemand menu, more program executables become available. Running ''busybox'' will summarize all available BusyBox commands. Entering ''command_name --help'' (two dashes) provides basic usage information for most applications.

BusyBox commands:
<code>
BusyBox v1.20.2 (2014-12-04 11:32:04 UTC) multi-call binary.
Copyright (C) 1998-2011 Erik Andersen, Rob Landley, Denys Vlasenko
and others. Licensed under GPLv2.

Currently defined functions:
        [, [[, addgroup, adduser, adjtimex, ar, arp, arping, ash, awk,
        basename, bunzip2, bzcat, bzip2, cal, cat, chgrp, chmod, chown,
        chpasswd, chroot, chrt, chvt, cksum, clear, cmp, comm, cp, cpio, crond,
        crontab, cut, date, dc, dd, deallocvt, delgroup, deluser, depmod, df,
        diff, dirname, dmesg, dnsdomainname, dos2unix, du, dumpkmap,
        dumpleases, echo, egrep, eject, env, ether-wake, expr, false, fbset,
        fdflush, fdformat, fdisk, fgconsole, fgrep, find, flock, fold, free,
        freeramdisk, fsck, ftpget, ftpput, fuser, getopt, getty, grep, gunzip,
        gzip, halt, hdparm, head, hexdump, hostid, hostname, hwclock, id,
        ifconfig, inetd, init, insmod, install, ipcalc, ipcrm, ipcs, kill,
        killall, killall5, klogd, last, less, linux32, linux64, linuxrc, ln,
        loadfont, loadkmap, logger, login, logname, logread, losetup, ls,
        lsmod, lsof, lzcat, lzma, md5sum, mesg, microcom, mkdir, mkfifo, mknod,
        mkswap, mktemp, modinfo, modprobe, more, mount, mv, nameif, nbd-client,
        nc, netstat, nice, nohup, nslookup, od, openvt, passwd, patch, pgrep,
        pidof, ping, ping6, pivot_root, pkill, poweroff, printenv, printf, ps,
        pwd, rdate, readlink, realpath, reboot, renice, reset, resize, rev, rm,
        rmdir, rmmod, route, rpm, rpm2cpio, script, sed, seq, setarch,
        setconsole, setkeycodes, setsid, sh, sha1sum, sleep, sort, split,
        start-stop-daemon, strings, stty, su, sulogin, sum, swapoff, swapon,
        switch_root, sync, sysctl, syslogd, tail, tar, taskset, tee, telnet,
        test, tftp, tftpd, time, timeout, top, touch, tr, traceroute, true,
        tty, udhcpc, udhcpd, udpsvd, umount, uname, uncompress, uniq, unix2dos,
        unlzma, unxz, unzip, uptime, usleep, vconfig, vi, vlock, watch, wc,
        wget, which, who, whoami, xargs, xz, xzcat, yes, zcat
</code> 

Most BusyBox commands will be familiar to Linux users. These commands are often more limited in functionality to their non-BusyBox equivalents. Running ''echo $PATH'' reveals all other common executable pathways take precedence over /bb/ (BusyBox), so importing and loading the full version equivalent from Debian/Ubuntu (eg. wget) will then provide the full version as default. Running ''which executable_name'' will confirm which version is actually being used. Remember in dCore, SCEs need to be both imported and loaded to become useful.

Commonly used dCore specific commands:
<code>
backup              # Perform regular backup (/etc/sysconfig/tcedir/mydata.tgz)
cpanel              # Open Control Panel.
exittc              # Open TC Exit Options GUI.
filetool.sh -b      # Perform regular backup ('backup' command above launches /usr/bin/filetool.sh -b).
filetool.sh -sb     # Perform safe backup (/etc/sysconfig/tcedir/mydatabk.tgz, then regular backup).
filetool            # Open Backup Restore and Lists Maintenance GUI.
fltk-editor         # Open default graphic editor or use 'fltk-editor file_name'
                    # or 'sudo fltk-editor file_name' for root files.
flrun               # Open FLRun Application Launcher.
mnttool             # Open Mount Tool GUI.
ondemand_SCE_name   # As /etc/sysconfig/tcedir/ondemand/ is in the default executable path,
                    # OnDemand SCEs can be quick loaded by simply entering the SCE name
                    # (eg. 'firefox' if Firefox is in OnDemand). Provided the executable name
                    # is the same as the SCE name, most applications with desktop files auto-launch.
sce-command --help  # Output SCE command help and usage information (eg. 'sce-import --help', two dashes).
sce-tools           # Open SCE Tools GUI.
screenshot.sh       # Take a screenshot, use 'sleep 5 && screenshot.sh' for time delay. 
services            # Open Services GUI.
top                 # Open top process monitor.
vi                  # Open default terminal editor 'vi' or use 'vi file_name' or
                    # 'sudo vi file_name' for root owned files, numerous tutorials online.
xkill               # Use skull cursor to select and kill problematic graphic applications,
                    # traditional 'kill' and 'killall' also available.
</code>

Several aliases are predefined in ~/.ashrc for user friendly outputs, quicker navigation and to prevent accidental file deletion. Items can be modified, removed or added as desired, defaults:
<code>
# Alias definitions.
alias df='df -h'
alias du='du -h'

alias ls='ls -p'
alias ll='ls -l'
alias la='ls -la'

# Avoid errors... use -f to skip confirmation.
alias cp='cp -i'
alias mv='mv -i'
alias rm='rm -i'

# Quick access to tcedir and scedir
alias tce='cd /etc/sysconfig/tcedir'
alias sce='cd /etc/sysconfig/tcedir/sce'
</code>

Terminal use is straightforward, basic generic Linux command examples below, numerous tutorials online:
<code>
cd                     # Change to home directory.
cd /desired/path       # Change directory to designated pathway, use tab autocomplete.
cd ..                  # Move up to parent directory.
cd -                   # Return to previous directory.
cp                     # Copy file(s).
mkdir                  # Make directory.
mv                     # Move file(s).
pwd                    # Print working directory.
rm                     # Remove file(s).
touch                  # Create file(s).
startx                 # Launch Window Manager or Desktop Environment from TTY.
Alt-SysRq-R-E-I-S-U-B  # Depress Alt-SysRq and enter R-E-I-S-U-B keys (in that order)
                       # to safely reboot from most major system problems.
Alt-SysRq-R-E          # If the GUI locks up this may allow graceful graphics exit
                       # to TTY, issue startx to restart Window Manager.
</code>

==== Window Manager usage ====
As dCore supports numerous Window Managers, it is not practical to summarize their usage here. Specific Window Manager documentation can readily be found online, most support user modified mouse behavior and keyboard shortcuts. With exception //flwm_topside// usage is summarized below (Fast Light Window Manager with title bar at top of window instead of rotated left), to give users installing from the dCorePlus ISO a head start. A variety of [[http://wiki.tinycorelinux.net/dcore:x-desktop|supported and unsupported Window Managers and Desktop Environments]] have been tested to work in dCore, it is easy to switch to another as desired.

=== flwm_topside Overview ===
The default flwm_topside Window Manager is lightweight and responsive. It requires only FLTK v1.1 as a dependency. Although it does not support mouse or keyboard customization without modifying the source code, usage and keyboard shortcuts are logical and straightforward. Being a supported dCore Window Manager, the main menu provides quick access to OnDemand SCE(s), System Tools, Control Panel and Exit dialogue.

=== flwm_topside Mouse Usage ===
Neither a traditional panel or even wbar is required, although wbar is included in the dCorePlus ISO. The applications and main menu can be accessed by clicking on free desktop space with any mouse button or by right clicking on any window title bar. All open applications are automatically listed in the main menu. Title bars are located horizontally across the top of the windows and include the window title. Mouse click on the top right window buttons: iconize window, toggle maximize horizontally, toggle maximize vertically and close window.  Menu items can be selected by clicking a highlighted item with any mouse button. New windows are smart placed based on open screen space and the mouse cursor is automatically moved to the top left corner of the new window. Re-position a window by holding left or middle click on the window title bar and dragging the window. Resize a window by holding left click on any corner or edge (cursor changes) and dragging the window smaller or larger.

=== flwm_topside Keyboard Shortcuts ===
<code>
Alt+F1                      # Iconize window
Ctrl Alt arrows             # Move window
Ctrl Alt =                  # Grow window (unshifted + key)
Ctrl Alt -                  # Shrink window
Ctrl Alt PgUp               # Grow window veritcally
Ctrl Alt PgDn               # Shrink window vertically
Ctrl Alt ,                  # Grow window hortizontally (unshifted < key)
Ctrl Alt .                  # Grow window hortizontally (unshifted > key)
Ctrl Alt t                  # Taller (sames as PgUp)
Ctrl Alt s                  # Shorter (same as PgDn)
Ctrl Alt m                  # Maximize window toggle
Ctrl Alt v                  # Maximize vertical toggle
Ctrl Alt h                  # Maximize hortizontal toggle
Alt Tab                     # Open applications and main menu
up/down/left/right arrows   # Navigate menu
spacebar                    # Select menu item

# FLWM optionally supports environment variable FLWM_TITLEBAR_COLOR to set color for window title bars.
# To set use hex rgb, e.g, 20:5F:20 (Currently supports fltk gtk+ scheme).
</code>

==== Kernel Updates ====
As documented in [[http://wiki.tinycorelinux.net/dcore:upgrading_kernel_and_initrd#dcore_kernel_updates|dCore Kernel Updates]], to provide stability kernels are not updated during the lifespan of the dCore port. It is, therefore, not necessary to check for or apply kernel updates. Similar to most Linux distributions, users with newer hardware should consider utilizing the newest dCore port available.

==== Base File System Updates ====
The dCore initrd file (base file system) is updated frequently due to active development and users have the option to track either stable or RC release. Although less tested, RC releases provide the latest bug fixes and features. Users wishing to assist with testing should run an up to date RC release before reporting bugs. Essentially the ''version -r'' (RC release) or ''version -c'' (stable release) commands are used to check and install base file system updates. Ensure the /etc/sysconfig/boot_path file is properly configured. Reboot the system to apply the update. Review [[http://wiki.tinycorelinux.net/dcore:upgrading_kernel_and_initrd#dcore_initrd_updates|dCore Initrd Updates]] for more information.

==== SCE Updates ====
As bug fixes and security releases become available, SCEs should be periodically updated. Review [[http://wiki.tinycorelinux.net/dcore:sce-update_command|dCore sce-update Command]] and [[http://wiki.tinycorelinux.net/dcore:extension_strategies#version_conflicts|Version Conflicts]] for more information. A system reboot is recommended to apply updates if outdated SCEs were already loaded during the session.

==== Persistence and System Changes ====
Like Tiny Core Linux, an installation is not persistent unless a TCE directory has been set up. This stores all imported SCE extensions so they are available across reboots. The TCE directory also stores the mydata.tgz backup file when running the ''backup'' command. By default this contains any files located in the home and opt directory. If it is necessary to add additional files for backup outside of these default directories, they should be entered into /opt/.filetool.lst. Any files or directories the user wants to exclude from ''backup'', to keep the backup file smaller, should be added into /opt/.xfiletool.lst. Although these files can be manually modified, when working in a graphic environment it may be easiest to use the Backup Restore GUI, launched by running ''filetool'' or accessed via System Tools -> Control Panel -> Backup/Restore.

Most system related configuration files are located in the /etc/sysconfig/ and /opt/ directories. Additional important configuration files for launching executables and applications at boot:
  * /opt/bootlocal.sh: Enter desired root commands to run in the background during system boot.
  * /opt/bootsyn.sh: Enter desired high priority root commands to run during system boot.
  * ~/.X.d/: Create a plain text file (not script) containing non-root commands to launch later in the boot cycle, typically graphic applications. For example, create a file named 'startups' containing:
<code>
conky &
dillo &
xset s 300 &
</code>

When using a persistent system, the ''backup'' command must be run before shutdown whenever configuration changes were made during the session, otherwise the data will be lost.

==== Backup ====
Since the kernel and initrd files are small and readily available from the Tiny Core website, it is not critical to routinely backup these files to other media. It is, however, possible to specify backups via /etc/sysconfig/boot_path during system updates, allowing a manual revert to an older version in case of a failed boot.

As all other critical files are stored within the TCE directory, a periodic copy/paste of this entire directory to other media effectively backs up the entire system, including SCE, mydata.tgz and mydatabk.tgz files.

When the system is set up and is running well, a safe backup should periodically be performed via ''filetool.sh -sb'', to copy mydata.tgz to mydatabk.tgz. Several mydata.tgz or mydatabk.tgz backup files can be manually saved if desired. The mydata.tgz file can be manually replaced with a known good version in the event of file corruption or system misconfiguration.

Although rare, there is a possiblity an updated SCE may not work correctly due to an RC bug, broken Debian/Ubuntu package or corrupt file system. Modifying SAFEBACKUP=TRUE in /etc/sysconfig/sceconfig will automatically backup the old SCE in /etc/sysconfig/tcedir/sce/backup/ when running ''sce-update'' or re-importing an SCE, which can be manually restored as needed. Note the modified /etc/sysconfig/sceconfig file needs to be added to /opt/.filetool.lst and ''backup'' run for the configuration change to be saved.

==== Maintenance ====
Aside from the updates and backups discussed above, dCore requires little maintenance. An advantage of using self-contained extensions that link to the main file system is that when the SCE is removed, all traces of the main program and dependencies are gone, no cruft left behind with the exception of home directory configuration files.

Optional periodic maintenance tasks:
  * Manually remove unneeded home directory files.
  * Run ''sce-debpurge'' and ''sce-debpurge -n'' to remove outdated and unneeded Debian (*.deb) files to reclaim drive space.
  * Run ''sce-remove'' to remove SCE(s) no longer required, reclaims drive space and improves ''sce-update -a'' (update all SCEs) efficiency.
  * If using /etc/sysconfig/sceconfig SAFEBACKUP=TRUE, manually remove old /etc/sysconfig/tcedir/sce/backup/ items as desired.

==== Resources ====
The above should help new users quick start a dCore system. More information is outlined in the dCore wiki and discussed in the dCore subforums:
  * FAQ: http://wiki.tinycorelinux.net/dcore:faq
  * Wiki: http://wiki.tinycorelinux.net/dcore:welcome
  * Forum (see dCore sections): http://forum.tinycorelinux.net/

**[[http://wiki.tinycorelinux.net/dcore:welcome|> Return to the dCore Wiki Welcome page]]**