Tweaking of Linux Live Scripts derivative used in Porteus
- fanthom
- Moderator Team
- Posts: 5667
- Joined: 28 Dec 2010, 02:42
- Distribution: Porteus Kiosk
- Location: Poland
- Contact:
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@skyhog99
good to see that LLS are alive i'm sure someone find it useful.
thanks!
BTW: did you implement any new features in these LLS which could be imported to Porteus?
(this thread is mainly about it)
good to see that LLS are alive i'm sure someone find it useful.
thanks!
BTW: did you implement any new features in these LLS which could be imported to Porteus?
(this thread is mainly about it)
Please add [Solved] to your thread title if the solution was found.
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@fanthom
With linus72's help I was able to resolve one pesky issue with the mount_device routine on USB sticks. The fs_options routine was using an option "users" that was bogus. Once I removed that option it was able to mount USB read-write just like the good 'ole days.
Other than that, nothing new.
Skyhog99
With linus72's help I was able to resolve one pesky issue with the mount_device routine on USB sticks. The fs_options routine was using an option "users" that was bogus. Once I removed that option it was able to mount USB read-write just like the good 'ole days.
Other than that, nothing new.
Skyhog99
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@fantom,
seems some problem in linuxrc script but I am not sure
Details
http://forum.porteus.org/viewtopic.php? ... =100#p3223
If you need more info please direct me how to collect
Posted after 4 days 1 hour 58 minutes 42 seconds:
Re: Tweaking of Linux Live Scripts derivative used in Porteus
Found out 2 problem problem for pxe boot in linuxrc
Here we have row:
The fix is following:
And in additional - for rootcopy also need some fix for httpfs permissions as /mnt/httpfs/porteus have 444 permission mode
This is happens due cp -a command which takes 444 mode and copy all files with --r--r--r---r--r--r---r--r--r--
In case of we have some binary or script in rootcopy/bin,sbin,/usr/bin,/usr/sbin,/usr/local/bin, etc - it won't start
In case if you have some fix - rootopy/etc/rc.d/rc.M,rc.S,rc.6 or other - it won't prevent booting or shutdown
Som some workaroung needed - to change permission for rootopy/bin,sbin,/usr/bin,/usr/sbin,/usr/local/bin,/etc/rc.d ... to 755 mode
ALso there additional patch for pxe boot script boot/pxelinux.cfg/start
see
http://forum.porteus.org/viewtopic.php? ... 3352#p3352
seems some problem in linuxrc script but I am not sure
Details
http://forum.porteus.org/viewtopic.php? ... =100#p3223
If you need more info please direct me how to collect
Posted after 4 days 1 hour 58 minutes 42 seconds:
Re: Tweaking of Linux Live Scripts derivative used in Porteus
Found out 2 problem problem for pxe boot in linuxrc
Here we have row:
After httpfs mounting it will be all *.xpm will be loaded to RAM - not only in porteus/base,modules,optional but all from drive /mnt/drive - which was provided by TFTP. If you have other catalogs with *.xzm it will be loaded also - and may cause to halt loading... mkdir -p /mnt/httpfs; httpfs http://$IP /mnt/httpfs
The fix is following:
... mkdir -p /mnt/httpfs/porteus; httpfs http://$IP/porteus/base /mnt/httpfs/porteus
And in additional - for rootcopy also need some fix for httpfs permissions as /mnt/httpfs/porteus have 444 permission mode
This is happens due cp -a command which takes 444 mode and copy all files with --r--r--r---r--r--r---r--r--r--
In case of we have some binary or script in rootcopy/bin,sbin,/usr/bin,/usr/sbin,/usr/local/bin, etc - it won't start
In case if you have some fix - rootopy/etc/rc.d/rc.M,rc.S,rc.6 or other - it won't prevent booting or shutdown
Som some workaroung needed - to change permission for rootopy/bin,sbin,/usr/bin,/usr/sbin,/usr/local/bin,/etc/rc.d ... to 755 mode
ALso there additional patch for pxe boot script boot/pxelinux.cfg/start
see
http://forum.porteus.org/viewtopic.php? ... 3352#p3352
- fanthom
- Moderator Team
- Posts: 5667
- Joined: 28 Dec 2010, 02:42
- Distribution: Porteus Kiosk
- Location: Poland
- Contact:
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@Falcony
valuable input - as usual
will see what i can do about it.
thanks a lot.
valuable input - as usual
will see what i can do about it.
thanks a lot.
Please add [Solved] to your thread title if the solution was found.
Re: Tweaking of Linux Live Scripts derivative used in Porteu
Not so as you vaueble support L)
- fanthom
- Moderator Team
- Posts: 5667
- Joined: 28 Dec 2010, 02:42
- Distribution: Porteus Kiosk
- Location: Poland
- Contact:
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@Falcony
"After httpfs mounting it will be all *.xpm will be loaded to RAM - not only in porteus/base,modules,optional but all from drive /mnt/drive - which was provided by TFTP."
should be ok now even without mkdir -p /mnt/httpfs/porteus. please test 32bit rc2 (when it will be out) and let me know if it works ok for you.
"some workaroung needed - to change permission for rootopy/bin,sbin,/usr/bin,/usr/sbin,/usr/local/bin,/etc/rc.d ... to 755 mode"
this makes no sense to me: what if user wants to put sticky bit or suid in /rootcopy/sbin/some_utility?
i could do chmod 755 on rc.S, rc.M and rc.6 as they are essential to booting/shutdown but i still have some concerns: changing attributes on a files makes aufs save them in /mnt/live/memory/changes. i'm worrying that user who uses 'changes-time' script may have saved them in every module he creates. if he made some tweaks to rc.* then they will be distributed to other people.
same story with "save-changes" script.
in my opinion it's better to create new xzm instead of using /rootcopy while using pxe-boot.
i know it's a longer way but for sure safer....
"After httpfs mounting it will be all *.xpm will be loaded to RAM - not only in porteus/base,modules,optional but all from drive /mnt/drive - which was provided by TFTP."
should be ok now even without mkdir -p /mnt/httpfs/porteus. please test 32bit rc2 (when it will be out) and let me know if it works ok for you.
"some workaroung needed - to change permission for rootopy/bin,sbin,/usr/bin,/usr/sbin,/usr/local/bin,/etc/rc.d ... to 755 mode"
this makes no sense to me: what if user wants to put sticky bit or suid in /rootcopy/sbin/some_utility?
i could do chmod 755 on rc.S, rc.M and rc.6 as they are essential to booting/shutdown but i still have some concerns: changing attributes on a files makes aufs save them in /mnt/live/memory/changes. i'm worrying that user who uses 'changes-time' script may have saved them in every module he creates. if he made some tweaks to rc.* then they will be distributed to other people.
same story with "save-changes" script.
in my opinion it's better to create new xzm instead of using /rootcopy while using pxe-boot.
i know it's a longer way but for sure safer....
Please add [Solved] to your thread title if the solution was found.
Re: Tweaking of Linux Live Scripts derivative used in Porteu
Thanks.
May be in case of pxe boot - the same way of behavor?
Any foolproof solution for such case is possible?
May be some warning on boot screen?
In simplest , for ex. if rootcopy is on FAT when cnanges do not using - what hapens with permissions /rootcopy files?this makes no sense to me: what if user wants to put sticky bit or suid in /rootcopy/sbin/some_utility?
i could do chmod 755 on rc.S, rc.M and rc.6 as they are essential to booting/shutdown but i still have some concerns: changing attributes on a files makes aufs save them in /mnt/live/memory/changes. i'm worrying that user who uses 'changes-time' script may have saved them in every module he creates. if he made some tweaks to rc.* then they will be distributed to other people.
same story with "save-changes" script.
May be in case of pxe boot - the same way of behavor?
Sure it is better - but in this case user have to know it - and that's more pitty - remember this.in my opinion it's better to create new xzm instead of using /rootcopy while using pxe-boot.
i know it's a longer way but for sure safer....
Any foolproof solution for such case is possible?
May be some warning on boot screen?
- fanthom
- Moderator Team
- Posts: 5667
- Joined: 28 Dec 2010, 02:42
- Distribution: Porteus Kiosk
- Location: Poland
- Contact:
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@Falcony
"if rootcopy is on FAT when cnanges do not using - what hapens with permissions /rootcopy files? "
ok you are right.
for pxe-boot all files in /porteus/rootcopy: /etc/rc.d, /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin (uff..) will be chmodded to 755.
"May be some warning on boot screen?"
hmmm.. i think we could add it to the FAQ instead (with wider explanation).
Ahau
could you add another Q/A to FAQ - something like:
Q:"i'm using /porteus/rootcopy for adding files to the live filesystem and all permissions are messed up. What's the story? (irish favorite question)"
A: "when /porteus/rootcopy folder is placed on FAT/NTFS then all files have 777 permissions due to Windows filesystem limitations.
when porteus is booted over network then all files from /porteus/rootcopy have 444 permissions (that's the way http service works). during the boot linuxrc will set 755 permissions on all scripts/binaries placed in /porteus/rootcopy: /etc/rc.d, /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin folders.
If you want to keep original permissions then you must use xzm module and not /rootcopy.
(REMINDER: all of the above applies to FAT/NTFS and pxe-boot only, you can use /porteus/rootcopy as normal when placed on supported linux fs)"
thanks in advance.
"if rootcopy is on FAT when cnanges do not using - what hapens with permissions /rootcopy files? "
ok you are right.
for pxe-boot all files in /porteus/rootcopy: /etc/rc.d, /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin (uff..) will be chmodded to 755.
"May be some warning on boot screen?"
hmmm.. i think we could add it to the FAQ instead (with wider explanation).
Ahau
could you add another Q/A to FAQ - something like:
Q:"i'm using /porteus/rootcopy for adding files to the live filesystem and all permissions are messed up. What's the story? (irish favorite question)"
A: "when /porteus/rootcopy folder is placed on FAT/NTFS then all files have 777 permissions due to Windows filesystem limitations.
when porteus is booted over network then all files from /porteus/rootcopy have 444 permissions (that's the way http service works). during the boot linuxrc will set 755 permissions on all scripts/binaries placed in /porteus/rootcopy: /etc/rc.d, /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin folders.
If you want to keep original permissions then you must use xzm module and not /rootcopy.
(REMINDER: all of the above applies to FAT/NTFS and pxe-boot only, you can use /porteus/rootcopy as normal when placed on supported linux fs)"
thanks in advance.
Please add [Solved] to your thread title if the solution was found.
- Ahau
- King of Docs
- Posts: 1331
- Joined: 28 Dec 2010, 15:18
- Distribution: LXDE & Xfce 32/64-bit
- Location: USA
Re: Tweaking of Linux Live Scripts derivative used in Porteu
FAQ added to doc on main site.
Thanks
fanthom
Thanks
fanthom
Please take a look at our online documentation, here. Suggestions are welcome!
Re: Tweaking of Linux Live Scripts derivative used in Porteu
OK--guys, I have officially test driven the new 64-bit Porteus Release Candidate 2!
I have good news and bad news. The good news is the desktop came up this time! Congratulations on fixing the bugs! I'm writing from Porteus now!
The bad news (and I hate to mention it, but I think this will greatly aid the building of Porteus) is that the boot script stopped me three or four times with warnings that I felt out of place--as if they were boot-stopping errors--notably the ones in red! Also, it felt as technical as installing a custom BSD spin--not the smooth Slax experience. The first new question I was asked in the form of what I thought first to be an error is to make a data save archive (.dat). Can't we instead have Porteus make one on first-time boot? What average Windows "user" is going to format their drive ext2? Complaining hard that the drive is not posix compatible is being about as unfriendly to Windows switchers as their OS is to Linux filesystems! This needs to either say something like "Porteus has detected you're using a Windows flash drive. Would you like to create a file to save your files? You can change this later in the boot menu." and then say "Please wait about 5 minutes while a file is generated..." or it needs to create it by itself--period.
Secondly, the new password change is a great implementation, but a new switcher to Porteus won't get it. I like the fact someone can just press enter, but this still does not make sense. Couldn't we make a GUI wrapper for this ONCE the computer is logged in and booted, then change the password on the next boot? Then again, I think the new password part is alright, since it keeps Porteus safer and all. Ubuntu seems to have a friendlier boot-up, but I think we can beat that! We need to be the best distribution ever!
As always, go Porteus!
I have good news and bad news. The good news is the desktop came up this time! Congratulations on fixing the bugs! I'm writing from Porteus now!
The bad news (and I hate to mention it, but I think this will greatly aid the building of Porteus) is that the boot script stopped me three or four times with warnings that I felt out of place--as if they were boot-stopping errors--notably the ones in red! Also, it felt as technical as installing a custom BSD spin--not the smooth Slax experience. The first new question I was asked in the form of what I thought first to be an error is to make a data save archive (.dat). Can't we instead have Porteus make one on first-time boot? What average Windows "user" is going to format their drive ext2? Complaining hard that the drive is not posix compatible is being about as unfriendly to Windows switchers as their OS is to Linux filesystems! This needs to either say something like "Porteus has detected you're using a Windows flash drive. Would you like to create a file to save your files? You can change this later in the boot menu." and then say "Please wait about 5 minutes while a file is generated..." or it needs to create it by itself--period.
Secondly, the new password change is a great implementation, but a new switcher to Porteus won't get it. I like the fact someone can just press enter, but this still does not make sense. Couldn't we make a GUI wrapper for this ONCE the computer is logged in and booted, then change the password on the next boot? Then again, I think the new password part is alright, since it keeps Porteus safer and all. Ubuntu seems to have a friendlier boot-up, but I think we can beat that! We need to be the best distribution ever!
As always, go Porteus!
- Ahau
- King of Docs
- Posts: 1331
- Joined: 28 Dec 2010, 15:18
- Distribution: LXDE & Xfce 32/64-bit
- Location: USA
Re: Tweaking of Linux Live Scripts derivative used in Porteu
RE: save.dat:
I have an idea for this, but I'm not sure if it's really workable, or if it's clean. let me know what you think:
1) Porteus ISO comes standard with a save.dat file, zipped up (save.dat.zip, save.dat.tar or whatever) (this is not necessary if initrd can create a standard sized .dat image in step 2, without a zipped image file)
2) New cheatcode, standard in porteus.cfg: 'autosave' -- autosave will check for posix compatibility. If the drive is posix compatible, changes are stored in /porteus/changes. If it is not posix compatible, it checks for /porteus/save.dat. If it exists, it mounts it for saving changes. If it does not exist, it extracts save.dat.zip to /porteus/save.dat and mounts it for changes. User is notified that this will occur, and that they can modify or move their save.dat image with porteus save.dat manager.
3) anyone who wants to put their changes elsewhere can delete the 'autochanges' cheatcode, and replace it with 'changes='.
This still stops the boot process for FAT and NTFS users, but will only require one key press to agree and extract the .dat container. After that, they would not need to alter their porteus.cfg in order to continue using save.dat (that's really the only improvement over the existing setup).
Otherwise, I think that we should keep the existing setup, but soften the language as agreimann suggests. I don't feel that Auto-creating a save.dat file would be a good idea. We'd get fails due to not enough disk space, or people wondering how their 300MB install suddently became 800MB, etc.,
I have an idea for this, but I'm not sure if it's really workable, or if it's clean. let me know what you think:
1) Porteus ISO comes standard with a save.dat file, zipped up (save.dat.zip, save.dat.tar or whatever) (this is not necessary if initrd can create a standard sized .dat image in step 2, without a zipped image file)
2) New cheatcode, standard in porteus.cfg: 'autosave' -- autosave will check for posix compatibility. If the drive is posix compatible, changes are stored in /porteus/changes. If it is not posix compatible, it checks for /porteus/save.dat. If it exists, it mounts it for saving changes. If it does not exist, it extracts save.dat.zip to /porteus/save.dat and mounts it for changes. User is notified that this will occur, and that they can modify or move their save.dat image with porteus save.dat manager.
3) anyone who wants to put their changes elsewhere can delete the 'autochanges' cheatcode, and replace it with 'changes='.
This still stops the boot process for FAT and NTFS users, but will only require one key press to agree and extract the .dat container. After that, they would not need to alter their porteus.cfg in order to continue using save.dat (that's really the only improvement over the existing setup).
Otherwise, I think that we should keep the existing setup, but soften the language as agreimann suggests. I don't feel that Auto-creating a save.dat file would be a good idea. We'd get fails due to not enough disk space, or people wondering how their 300MB install suddently became 800MB, etc.,
Please take a look at our online documentation, here. Suggestions are welcome!
- fanthom
- Moderator Team
- Posts: 5667
- Joined: 28 Dec 2010, 02:42
- Distribution: Porteus Kiosk
- Location: Poland
- Contact:
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@agreimann
"The first new question I was asked in the form of what I thought first to be an error is to make a data save archive (.dat). Can't we instead have Porteus make one on first-time boot?"
for sure new members would feel more comfortable in GUI when creating .dat container. We have a .dat manager written by brokenman so maybe there is no point for stressing users with CLI.
@all
what about:
- linuxrc discovers FAT/NTFS and prints a message like:
"Porteus has detected you're using a Windows filesystem (FAT/NTFS) on a booting media. Changes can't be saved on this fs due to posix incompatibility. Once booted to Porteus desktop, please use "Porteus Save Manager" to create .dat container formatted with linux filesystem and use it for saving your changes.... .... ....."
- sleep 5 secs
- continue in "Always Fresh"
"Secondly, the new password change is a great implementation ... Couldn't we make a GUI wrapper for this ONCE the computer is logged in and booted, then change the password on the next boot?"
this was proposed before by Blaze, pls find my response here:
http://porteus.org/forum/viewtopic.php?f=53&t=463#p3274
i would leave this function in place - maybe we could add more info why changing default passwords is important (simple reason: everybody knows it).
any ideas what else?
@Ahau
could be done but it makes things even more complicated (new cheatcode, what if user deletes zipped dats?, etc...)
"The first new question I was asked in the form of what I thought first to be an error is to make a data save archive (.dat). Can't we instead have Porteus make one on first-time boot?"
for sure new members would feel more comfortable in GUI when creating .dat container. We have a .dat manager written by brokenman so maybe there is no point for stressing users with CLI.
@all
what about:
- linuxrc discovers FAT/NTFS and prints a message like:
"Porteus has detected you're using a Windows filesystem (FAT/NTFS) on a booting media. Changes can't be saved on this fs due to posix incompatibility. Once booted to Porteus desktop, please use "Porteus Save Manager" to create .dat container formatted with linux filesystem and use it for saving your changes.... .... ....."
- sleep 5 secs
- continue in "Always Fresh"
"Secondly, the new password change is a great implementation ... Couldn't we make a GUI wrapper for this ONCE the computer is logged in and booted, then change the password on the next boot?"
this was proposed before by Blaze, pls find my response here:
http://porteus.org/forum/viewtopic.php?f=53&t=463#p3274
i would leave this function in place - maybe we could add more info why changing default passwords is important (simple reason: everybody knows it).
any ideas what else?
@Ahau
could be done but it makes things even more complicated (new cheatcode, what if user deletes zipped dats?, etc...)
Please add [Solved] to your thread title if the solution was found.
Re: Tweaking of Linux Live Scripts derivative used in Porteu
Glad my suggestions could be of help!
It's cool how Blaze thinks of the same ideas sometimes. I agree that we should save the changing passwords for a later time--and not put that in startup. In other words, we should have a GUI program do that--I'll explain my thinking in a second.
As for the save.dat process, I also agree that using a GUI would be much better with the manager. Perhaps, we could have a welcome box on startup like Linux Mint (maybe this welcome box will be the project I'll work on?) and have the .dat manager open automatically? To me, this would be the best for newbies to Porteus... And, yeah, I agree in the thinking that the part in the startup scripts being unfriendly to FAT32 and NTFS flash drives, considering that's where a lot of our users most likely will come from, should be removed or commented out!
OK--what I mean by a "welcome box" is actually not really like Mint, but more like what Windows would call a "wizard" or what Thunderbird does when you first open it, etc., that would welcome someone to Porteus, and guide them through setting it up for the first time. It would call an application up (say, the save.dat manager), continue when the user closed it, then work on changing the password(s), and say that the whole setup process is complete and that the user "is ready to go". We could do this very simply, without even needing to meddle with Python or C, really, sticking to fundamental Linux. Let me know what you think... because that'd be easy enough for me to code up.
Thanks, guys!
It's cool how Blaze thinks of the same ideas sometimes. I agree that we should save the changing passwords for a later time--and not put that in startup. In other words, we should have a GUI program do that--I'll explain my thinking in a second.
As for the save.dat process, I also agree that using a GUI would be much better with the manager. Perhaps, we could have a welcome box on startup like Linux Mint (maybe this welcome box will be the project I'll work on?) and have the .dat manager open automatically? To me, this would be the best for newbies to Porteus... And, yeah, I agree in the thinking that the part in the startup scripts being unfriendly to FAT32 and NTFS flash drives, considering that's where a lot of our users most likely will come from, should be removed or commented out!
OK--what I mean by a "welcome box" is actually not really like Mint, but more like what Windows would call a "wizard" or what Thunderbird does when you first open it, etc., that would welcome someone to Porteus, and guide them through setting it up for the first time. It would call an application up (say, the save.dat manager), continue when the user closed it, then work on changing the password(s), and say that the whole setup process is complete and that the user "is ready to go". We could do this very simply, without even needing to meddle with Python or C, really, sticking to fundamental Linux. Let me know what you think... because that'd be easy enough for me to code up.
Thanks, guys!
- fanthom
- Moderator Team
- Posts: 5667
- Joined: 28 Dec 2010, 02:42
- Distribution: Porteus Kiosk
- Location: Poland
- Contact:
Re: Tweaking of Linux Live Scripts derivative used in Porteu
@all
i'm not happy with default mount options in linuxrc which lets unprivileged users to unmount every partition in the system (while they should deal with removable ones only).
i have decided to change default set from:
to
'nodiratime' should increase the performance - same way as 'noatime' does.
removed 'users' option wont allow unprivileged users to mess with internal devices/partitions.
let me know if you think we should drop suid, dev or exec as well.
Second thing (and as a fallback to above):
as you probably know /etc/fstab is created during every boot and changing mount options means that you have to modify linuxrc and initrd.
i would like to make the users life easier (sic!) and introduce new cheat called 'mopt' (mount options), here is the rough description:
Reference: 'man mount'
@Ahau
please fix my "ponglish" and update cheatcodes.txt. Thanks in advance
i'm not happy with default mount options in linuxrc which lets unprivileged users to unmount every partition in the system (while they should deal with removable ones only).
i have decided to change default set from:
Code: Select all
noatime,users,suid,dev,exec
Code: Select all
noatime,nodiratime,suid,dev,exec
removed 'users' option wont allow unprivileged users to mess with internal devices/partitions.
let me know if you think we should drop suid, dev or exec as well.
Second thing (and as a fallback to above):
as you probably know /etc/fstab is created during every boot and changing mount options means that you have to modify linuxrc and initrd.
i would like to make the users life easier (sic!) and introduce new cheat called 'mopt' (mount options), here is the rough description:
Code: Select all
Default mount options for all filesystems in Porteus are: "noatime,nodiratime,suid,dev,exec"
Use this cheatcode if you want to specify your own set. Each option must be separated with a comma "," no spaces are allowed between them.
Example:
mopt=realtime,sync,users,nosuid,noexec"
@Ahau
please fix my "ponglish" and update cheatcodes.txt. Thanks in advance
Please add [Solved] to your thread title if the solution was found.
- Ahau
- King of Docs
- Posts: 1331
- Joined: 28 Dec 2010, 15:18
- Distribution: LXDE & Xfce 32/64-bit
- Location: USA
Re: Tweaking of Linux Live Scripts derivative used in Porteu
How's this look?
Code: Select all
mopt
... This cheatcode will allow you to customize your filesystem
mount options. By default, the mount options for all
filesystems in Porteus are: "noatime,nodiratime,suid,dev,exec".
Each option must be separated wtih a comma "," with no spaces
between any characters.
Example: 'mopt=realtime,sync,users,nosuid,noexec'
see 'man mount' for more information on specific mount options.
Please take a look at our online documentation, here. Suggestions are welcome!