Toasterson/The Gist of the illumos Rust API.md

## The Gist of the illumos Rust API.md

      
    Raw
  

              The Gist of the illumos Rust API.md
            
          
    The Gist of things we should have in illumos-rs

When we make applications and libraries interacting with illumos there are a couple of common things everybody needs to do.
On one hand operating the Systems tools to manage things like links but also to edit and manage files.
Configuration management is out of scope for this library but some of the parts of it should have idempotent components
(the Rust Standard library already has the others and we use those when needed)
When implmeneting some of these it will initially need a need that justifies it. But once that person has done it and contributed their work
we will see others making application because it gets easier.
I see the following components as part of the library:
file

The Rust standard library has all functionalities of Unix files covered but they are split into seperate modules due to Rusts portability
requirements. We should import all the functions and either wrap or re-export the full unix filetype including capability to modify owner group times etc.
Additionally Idempotent functionality should be added either via type extension so that we can say.
See std::os::unix::fs.
In the stdlib reading of user and times is currently supported but not changing. At least in stable. And just asking people to always use nightly is not that good.
Since we can use independant functions for owner and group we also don't need to use option to specify to leave that specific field unchanged.
use illumos::file::FileExt;
use std::fs::DirBuilder;
use std::os::unix::fs::DirBuilderExt;

let mut file = illumos::file::File::open("path/to/file.txt")?;
file.ensure_content("Blubber")?;
file.owner(1000)?;

let builder = DirBuilder::new().recursive(true).owner("toasty").mode(0o755);
builder.create("/path/to/dir")?;
builder.create("/path/to/dir2")?;
link management

If that is via direct library bindings or wrapping dladm and ipadm we will need basic link route and dns resolver management.
nss and pam seem like seperate out of scope topics for us especially since those are shared formats. flowadm could come in handy
but that might warrant it's own library.
ips

Ips is the default package manager for all big distributions and even though we support others they are (with one expection) not the systems package manager.
Having the simple capabilities to change install remove packages with functions is usefull. I propose though to gate it behind a Image struct though so it gets
easier to reference the correct IPS image when chaning things.
use illumos::ips::{Image, PublisherOptions};

let root_image = Image::open(None)?;
root_image.install_package("system/header")?;
let pub_opts = PublisherOptions::new("solarm.org").url("https://pkg.solarm.org/braich").remove_url("https://pkg.omnios.org/braich");
root_image.set_publisher(&pub_opts)?;
root_image.unset_publisher(&pub_opts)?;
SMF

Same as for IPS. Since the SMF utilities can operate also on non default locations we should expose an "Image" which people edit by default.
use illumos::smf::{Repository, ImportOptions};

let repo = Repository::default()?;
repo.import("/path/to/manifest")?;
// May be a bit too simple example
repo.import_with(ImportOptions::new().validate()).import("/path/to/manifest")?;
A more complete example would be
svccfg -s pkg/server <<EOF
add ${BRANCH_NAME}
select ${BRANCH_NAME}
addpg pkg application
setprop pkg/port=${nextport}
setprop pkg/readonly=true
end
EOF
let repo = Repository::default()?;

repo.select("pkg/server")
  .add_instance("braich") //Select is implied
  .add_property_group("pkg", "application") //or .add_property_group("pkg/application")
  .set("pkg/port", 10001)
  .set("pkg/readonly", true)
  .commit()?;
An Alernate route would use
let repo = Repository::open("path/to/repo.db")?; //name might change depending if wen need to add /etc... to this path or just the sysroot path
ZFS

I think we should make an API like this
use illumos::zfs::{ZPool, Dataset, Vdev, Compression, ShareOptions};

let rpool_mirror_vdev = Vdev::new("mirror").add("c0t0d1").add("c0t0d2");

let rpool = ZPool::with_ashift(9).with_comment("an intelligent comment").with_feature("async_destroy").add_vedv(rpool_mirror_vdev).add_spare("c2t0d0").create("rpool")?;

let ds1 = rpool.create_dataset("ROOT")?;
let ds2 = ds1.create_dataset("braich")?;
let export = rpool.dataset_builder().with_mountpoint("/export").with_compression(Compression::LZ4).create("export")?;
let export_home = export.create_dataset("home")?;
export_home.share(ShareOptions::nfs().v3_allow("192.168.0.0/24"))?;
lofi

use illumos::lofi::{Lofi, File};

let backing_file = File::create("/path/to/file")?; //Wrapping mkfile and not making an std::fs::File here
let lofidev = Lofi::open(&backing_file)?;

// some operations on the device.
let n = lofidev.name();
lofidev.remove()?;

let fs_rev = backing_file.get_file()?; //Return a new std::fs::File here
util

Some misculaneous things we will need a clear API for which do not ahve their own place as its, few things.

List Disks
Blink Disk LED (Or that maybe in a disk module?)
devinfo?
devfsadm?

Things we thus far havent used in Rust that probably could get their own modules or have their own crates already


RBAC
Zones
DTrace