Manuals/starter

this manual is intended as a basic introduction into Computercraft's CraftOS and Minux

0 - getting started:

- Installing minux

after installation, minux will start with either a menu or a prompt, depending on your choice. if you chose menu, you can open a prompt in the menu, if you selected prompt as bootup UI you can start the menu by typing "minux"

1 - file management

1.1 - listing disk content

1.1.1 - regular listing, ls

to list the files in the current directory, type "ls", minux will now show all the files in the current folder.

you can see that one of the folders listed is "/bin", another is "/etc", look for these, we will use them.

you can list files from a folder on another location by adding that as a "syntax variable", this is just an extra argument you provide to the program so it knows what you want it to do.

this can be done by running the program, then the argument, in this case, run "ls bin", it will now show you the contents of the /bin directory.

you can do this listing from any location by providing the "absolute path", or the full location of the folder you want to list, in this case, this is "/bin". the leading / indicates that you are starting from the root folder, or "/".

1.1.2 - additional info, ls -a

minux allows extra details when listing a folder, it can show if an object found is a folder or a file and how big this file is. this can be done by adding "-a" (additional info) as a last argument, eg: "ls /bin -a", minux will now show you more details on the contents of /bin.

1.1.3 - recursive listing, ls -r

you can also list not only the contents of a specific folder, but also all it's sub-directories and their contents, this can be done by adding "-r" (recursive), try this, run "ls /etc -r", minux will now show you the contents of /etc and all its subdirectories.

1.2 - changing working directory - cd

by default, craftOS and minux start in the root "/" folder, from here we can go to any folder on the disk. this is done with the "cd" command.

run "cd bin", now run "ls", you'll see that you now get to see the contents of /bin without having told to list that folder specifically, this is because you are now in that folder. minux will tell you this by showing the working folder just before where you type your command.

you can go up one folder with "cd ..", minux will now return to / since that is directly above /bin

you can go straight to another folder if you know it's name and location without having to go trough each folder seperately, this can be done by running cd followed by the absolute path, eg: to jump directly to /etc/minux-main, simply run "cd /etc/minux-main", you can do this from any location, making switching folders far faster.

1.3 - creating folders - mkdir

to make a new folder, we use the "mkdir" command, let's make a test folder.

first, make sure we are in "/", so "cd /". now we can make our test folder.

run "mkdir test", then do "ls", you'll see there's a new folder here called /test.

as usual, making folders with absolute path works, eg: "mkdir /test/test2" will create both /test and /test/test2.

1.4 - deleting files/folders - rm

you can delete files or entire folders using the "rm" command, so let's delete the testfolder we made with mkdir,

run "rm /test", then "ls /", you'll see that our testfolder is no longer there.

this works with any file or folder, deleting folders also deletes their entire contents.

Wildcards are an option here, such as "*" wich just means "everything", eg: "rm /test/*" would delete all contents in /test/, "rm /*" in effect cleans out the entire computer.

1.5 viewing/editing file contents

1.5.1 - catonize - cat

cat is a very simple program, it takes a text file and prints it. that's it. it can be told to halt every screen by adding "p" as final argument.

to catonize a file, simply run "cat filename", it will print it on your screen.

for bigger files, you are best off using "less"

1.5.2 - less - more then cat!

less is a more advanced version of cat, it opens a file and allows you to browse and scroll trough it, up and down, allowing you to read a file in a comfortable way without fearing you'd change it, great for inspecting config files.

1.5.3 - edit - file editor

minux comes with it's own editor wich is a more advanced version of the regular CC editor, it is run with the command "edit", if followed by a filename it will automatically open that file.

eg: "edit" simply opens the editor wich then asks you what file, "edit test.txt" opens the file "test.txt" straight up and starts editing that.

this is usefull for changing configuration files manually if you chose to do this.

1.6 - Bash operators

bash has some additional operators you can use to run commands, as for now there is only one but more will be added in the future.

1.6.1 - "&&" operator

this operator is added to the end of a command so the user can enter a new command directly behind it, both will be run as seperate commands,

eg: "apt -s goldcube && apt -i goldcube" will run the command to set the goldcube repo servers and then run the command to install goldcube.

2 - local user management

while some commands and ideas are taken over to network, this guide is for local user account specifically.

2.1 - adding users - useradd

users can be added with a single command called "useradd", you have to be "root" user to use this since that is the admin account.

you first call the command and as arguments you give the username and then the password, so let's test this.

run "useradd foo bar", minux will tell you the user has been added, now lets try this user and log in as it,

run "login foo bar", you'll see minux now logs in as the user "foo".

2.2 - changing passwords - passwd

changing passwords can be done with the program "passwd", it takes the target username and password as arguments.

let's try this by changing the user "foo"'s password (create the user if you need to). first log in as root (use "login")

run "passwd foo faa", now try to log in as this user with "login foo faa".

a user can change their own password, to change another user's password you need to be an admin (root).

2.3 - deleting users - userdel

to delete a user, we use "userdel", it works the same way as useradd but doesn't require the user's password.

so let's delete the user "foo", log in with your root account (type "login") and then run "userdel foo", the user is now deleted.

3 - system settings

General system settings can be changed using the "config" command, it takes two arguments, first is the configuration to be changed and the second argument is the change you want to do.

eg: minux has an auto-update system, this is disabled by default but can be turned on, to do this we need to call the program config with the first argument "update" and the second argument what setting we want to set it as, in this case "enabled".

run "config update enabled", minux won't say anything, but if you reboot and you pay attention you'll notice the updater launching before login, tough depending on your internet speed and software installed this can go very fast.

config can change a couple things, we have seen update but that's just one of it's functions.

3.1 - automatic updates

minux has three modes for automatic updates, "disabled", "enabled" and "always". these can be changed by running "config update %option%" where %option% is the setting you want.

disabled and enabled are straight forward enough, "always" means the updater will always reinstall everything on reboot, this is used for testing and development purpuses.

3.2 - login method

minux has three modes to handle user accounts, those being "disabled", "local" and "network".

when "disabled", minux will never ask for a username and assume the user "foo" for techincal purpuses, in effect this system never requires a password.

when set to "local" minux will use local login data stored on your pc, it's not as secure as networked but still better then disabled.

when set to "network" minux will seek a DHCP and AUTH server (these must exist already!) and use them to verify user data, this is the most secure method but also the hardest to set up.

just as with updates, this can be changed with "config login %option%"

3.3 - bootup UI

minux has three possible UI options available at this time, "menu", "prompt" and "workspace".

"menu" is what the name suggests, a menu system. it's easy to use if you don't know the commands but limited in it's abilities. you can open this menu at any time by running the command "minux".

"prompt" is the CraftOS shell.lua, slightly adjusted for minux's purpuses. it's basic but also very stable, included mostly for compatibility with other software.

"workspace" is a very powerfull multiple shell manager system written by LDDestroier, it allows just about everything the basic shell allows but also an unlimited amount of them, to see how to operate this run "man workspace".

just as with updates, this can be changed with "config ui %option%"

3.4 - debug mode

minux has a "debug mode", mostly intended for debugging and testing as the name suggests, but it also allows for troubleshooting help.

it has four modes, "disabled", "enabled", "logging" and "full".

"disabled" is the default mode and in this case debug does nothing at all. this is the least stressfull for your system and the kindest to your eyes.

"enabled" turns on debug print messages, making minux VERY talkative reporting on every step it takes.

"logging" writes the debug messages into log files in /var, programs can chose their own log files so there might be a few in there.

"full" turns on both screen prints and logging, giving you as much information as possible.

WARNING: due to limited disk space on CC computers it is highly advised not to turn on logging permanently, use at your own risk!

4 - crash handler - shutting down properly

Minux comes with a crash handler, just like RL operating systems do. it will remember how many attempts it did to restart and after 3 failed attempts it will drop you into a "resque shell" in stead, stopping just before the last point it managed to safely start, so if a program breaks your system minux will intervene and allow you to repair your system in stead of turning it into a brick.

this does come with a downside that the user should be aware off, simply turning off the computer with the button will appear to the crash handler as if the computer unexpectedly shut down (crashed), so after a couple times of doing this you won't be greeted with your regular workspace shell or menu but rather with a resque shell.

to avoid this, shut down the computer by using either "halt", "shutdown", "reboot" or "restart". in the menu, chose the "s" or "r" options.

5 - apt software manager

in game, type "man apt" in a computer for a detailed explaination right there. you can also open a newtab and run manuals in those to switch easy between prompt and manual

you can find extra software to install over here

5.1 Installing software

- "apt -i packname" : installs "packname"

this will attempt to install "packname" on this computer, rather straight forward. it will automatically install all dependency's the developer marked ad well.

5.2 removing software

- "apt -r packname": removes "packname"

this will attempt to remove "packname" from this computer, it will not delete the dependency's that came with it. if the developer was nice and provided the correct instructions additional files should also get cleared out with this.

5.3 updating software

5.3.1 version check

- "apt -u"

apt will compare the repository's version files with the software installed on your system and if this is a mismatch re-install the package. packages that have a matching version number will get skipped.

5.3.2 forced update

- "apt -U"

reinstalls everything (use when broken, this also works when booting with a bootdisk, use "/bin/apt.sh -U")

apt will reinstall every installed package regardless of version number, this will forcefully reset all known software to the repository's version.

5.4 apt listings

5.4.1 listing installed software

- "apt -l"

provides a list of all installed software, opens the file in an editor so you can scroll trough the list.

5.4.2 listing available software

- "apt -la"

retrieves the lists of available software from all known apt repository sources and opens this list in an editor so you can scroll trough it.

5.4.3 list used repository sources

- "apt -ls" : lists your current apt sources.

prints a list of your current apt repository sources.

5.5 changing repository sources

5.5.1 adding a url to the list

- "apt -s URL" : adds a new repository source to this computer, this is used for 3rd party developers or mirrors.

apt will test "url" and see if it can find the required repository files, if they are found this url will be added as an available repository source

5.5.2 resetting apt sources

"apt -s default"

clears the list of all repository sources and adds the default stable.

can be replaced with beta or goldcube.

5.5.3 removing a url from the list

- "apt -c URL : removes an apt source from the list.

removes a url from the repository source list, remember to uninstall the associated software first!

6 - workspace UI keybinds

Workspace, developed by LDDestroier, allows the user to create new windows on the fly, in effect making multitasking a breeze. it runs by default if the ui settings are set to workspace (run "config ui workspace").

Origional version can be found @ https://forums.computercraft.cc/index.p ... 61.new#new

CTRL+SHIFT+Arrow keys to move between workspaces.

CTRL+SHIFT+TAB+Arrow keys to swap the currently selected workspace with another.

CTRL+SHIFT+[WASD] to add a new workspace.

CTRL+SHIFT+Q to delete a workspace.

CTRL+SHIFT+P to pause a workspace.

You can even use CTRL+SHIFT+Mouse1 to click and drag to navigate between workspaces!

you are now ready to start installing software or set up a rednet dhcp and authentication system