~sergiusens/snappy/uidGid : revision 265

1

# Frameworks

2

## Definition

3

Frameworks are a direct extension of the Ubuntu Core. As such Frameworks have

4

the following attributes:

5

6

* Frameworks exist primarily to provide mediation of shared resources (eg,

7

device files, sensors, cameras, etc)

8

* Frameworks provide a significant benefit for many users

9

* Frameworks are delivered via snaps

10

* Frameworks can be installed on the same system without conflicts

11

* Frameworks typically will use a toplevel namespace

12

* Framework `binaries` may be used without appending the package name and

13

these binary names are governed by the framework onboarding process (below)

14

* Frameworks run in a carefully crafted security profile

15

* Frameworks are tightly coupled with separately maintained security policies

16

that extend the security policy available to apps consuming a framework

17

* Frameworks are developed and iterated by parties that have a contractual

18

relationship with Canonical

19

* Frameworks in the official Ubuntu store are designed jointly with Canonical

20

as part of the framework onboarding process

21

* Framework policies in the official Ubuntu store are controlled, designed,

22

and developed by Canonical with the framework authors as part of that process

23

* Framework policy will automatically be installed when a framework is

24

installed

25

* Unlike apps, frameworks have special permissions which allow them elevated

26

access to the system. For the official Ubuntu store, a contract will include

27

terms to ensure framework safety and maintenance

28

29

Importantly, frameworks are not generally:

30

31

* used as a replacement mechanism for debs/rpms

32

* used as a method to share code (ie, don't create a framework with libraries

33

just for the sake of apps to be able to use them)

34

* used as a method to bypass app isolation

35

* able to be forked (a user may of course always sideload a modified framework)

36

37

Note: snappy frameworks are somewhat different from the Ubuntu for Phones

38

[click frameworks](https://wiki.ubuntu.com/Click/Frameworks) and are more

39

flexible. Most importantly, click frameworks for Ubuntu for Phones map to a

40

particular release and are contracts between the platform (OS) and apps. Snappy

41

splits out the platform (OS) and the framework such that the contract is split

42

between the `framework` and the platform `release` (OS) (the `release` and

43

installed `frameworks` can be seen via `snappy info`). As such, apps will

44

specify the release they target (implementation covered elsewhere) and any

45

frameworks they require.

46

47

## Store process

48

Initially, frameworks and framework policy will be shipped in the same snap

49

which will ensure that framework policy is always in sync with the framework

50

for which it applies. To support this:

51

52

* Frameworks must always specify framework policy, otherwise the store will

53

reject it

54

* Framework snaps will always trigger a manual review to ensure the

55

framework policy has not changed. Alternatively, the first upload could

56

require manual review, but subsequent uploads could be automatically

57

approved if the security policy does not change

58

* For frameworks shipped in the official Ubuntu store, framework authors will

59

enter a contract to provide any needed security updates and not be malicious

60

61

For the official Ubuntu Store, we may eventually allow separate ownership of

62

frameworks from framework policies.

63

64

## Usage

65

### framework yaml

66

67

For frameworks, meta/packaging.yaml should contain something like:

68

69

name: foo

70

version: 1.1.234

71

type: framework

72

services:

73

- name: bar

74

description: "desc for bar service"

75

start: bin/bar

76

binaries:

77

- name: bin/baz

78

description: "desc for baz binary"

79

80

Required fields for framework snaps:

81

82

* `type: framework` - defines the type of snap this is

83

84

Frameworks will typically need specialized security policy. See `security.md`

85

for details.

86

87

In addition to the above yaml fields, the security policy used by apps is

88

shipped in the `meta/framework-policy` directory according to the following

89

hierarchy:

90

91

* `meta/framework-policy/`

92

* `apparmor/`

93

* `policygroups/`

94

* `group1`

95

* `group2`

96

* `templates/`

97

* `template1`

98

* `template2`

99

100

Because frameworks must be coinstallable, all shipped policy files will be

101

prepended with the framework name followed by an underscore. Apps must

102

reference the policy using the full name. For example, if the `foo` framework

103

ships `meta/framework-policy/apparmor/policygroups/bar-client`, then apps must

104

reference this as `foo_bar-client`.

105

106

While the above provides a lot of flexibility, it is important to remember a

107

framework snap need only provide what apps will use. For example, if the `foo`

108

framework is designed to have clients connect to the `bar` service over DBus,

109

then the framework snap might provide

110

`meta/framework-policy/apparmor/policygroups/foo_bar-client` and nothing else.

111

112

The contents of files in the `apparmor` directory use apparmor syntax as

113

described in `apparmor.d(5)`. When specifying DBus rules, set the peer label to

114

refer to the AppArmor label (`APP_ID`) of the service to be accessed. Also, to

115

ensure frameworks are coinstallable, the service should be implemented so its

116

DBus `path` uses the format `/pkgname/service`.

117

118

For example, using the above example where the `foo` framework ships a `bar`

119

DBus system service, a `bin/exe` utility, some data files and also a runtime

120

state file, then `meta/framework-policy/apparmor/policygroups/bar-client`

121

might contain something like:

122

123

/apps/foo/*/bin/exe ixr,

124

/apps/foo/*/data/** r,

125

/var/lib/apps/foo/*/run/state r,

126

dbus (receive, send)

127

bus=system

128

peer=(label=foo_bar_*),

129

130

### App yaml

131

132

For apps wanting to use a particular framework, meta/package.yaml simply

133

references the security policy provided by the framework. Eg, if a service in

134

the `norf` app wants to access the `bar` service provided by the `foo`

135

framework in the above framework yaml example, it might use:

136

137

name: norf

138

version: 2.3

139

frameworks:

140

- foo

141

services:

142

- name: qux

143

description: "desc for qux service"

144

start: bin/qux

145

caps:

146

- networking

147

- foo_bar-client

148

149

See `security.md` for more information on specifying `caps` and a

150

`security-template` as provided by the framework snap.

151

152

### User experience

153

154

The command line experience is:

155

156

$ snappy search foo

157

Name Version Description

158

foo 1.1.234 The foo framework

159

160

$ snappy install foo

161

Installing foo

162

Starting download of foo

163

4.03 MB / 4.03 MB [==============================] 100.00 % 124.66 KB/s

164

Done

165

Name Date Version Summary

166

foo 2015-03-16 1.1.234 The foo framework

167

168

$ snappy list

169

Name Date Version Summary

170

ubuntu-core 2015-03-16 333 ubuntu-core description

171

foo 2015-03-16 1.1.234 The foo framework

172

hello-world 2015-02-23 1.0.5

173

174

$ snappy list --updates

175

Name Date Version

176

ubuntu-core 2015-03-16 333 ubuntu-core description

177

foo* 2015-03-16 1.1.234 The foo framework

178

hello-world 2015-02-23 1.0.5

179

180

$ sudo snappy update

181

Installing foo (1.1.235)

182

4.03 MB / 4.03 MB [==============================] 100.00 % 124.66 KB/s

183

Done

184

Name Date Version Summary

185

foo 2015-03-17 1.1.235 The foo framework

186

187

$ snappy list --updates

188

Name Date Version

189

ubuntu-core 2015-03-16 333 ubuntu-core description

190

foo 2015-03-17 1.1.235 The foo framework

191

hello-world 2015-02-23 1.0.5

192

193

$ snappy remove foo

194

Removing foo

195

196

$ snappy info

197

release: ubuntu-core/devel-proposed

198

architecture: amd64

199

frameworks: foo

200

apps: hello-world

201

202

A convenience afforded to frameworks is that commands don't require that the

203

package name be appended. Eg, using the above `package.yaml`, either of these

204

may be used:

205

206

$ baz --version

207

1.1.235

208

209

210

## Open questions

211

212

The following are considerations that may affect the above for when we build on

213

this work:

214

215

* define how to specify restricted security policy (perhaps simply refine

216

what we do on Touch with meta information contained in the policy)

217

* define how to allow certain apps to use restricted policy without manual

218

review (perhaps have the framework define which apps are allowed to use the

219

restricted policy. How? in the yaml? in the meta information in the policy?

220

Something in the `meta/framework-policy` directory?)

221

* should we adjust `hw-assign/create svc-assign` to support special framework

222

services that perhaps don't provide sufficient app isolation, are privileged

223

in some manner, etc? Eg, consider a DBus service that allows you to

224

configure network interfaces. Framework provides the `bar-srv` service and

225

app `baz-app` declares it wants to use that service via `caps`. In the

226

normal case, declaring in `caps` would be enough, but `bar-srv` is special

227

in some way that we don't want the app to have access automatically. In this

228

case we might use:

229

230

`snappy svc-assign baz-app bar-srv`

231

232

* if we implement this, how should we declare `bar-srv` access to `bar-srv` is

233

restricted in this manner?

234

* should we allow users the ability to to use the `binaries` with the appended

235

package name? Eg:

236

$ baz.foo --version

237

1.1.235

238

* ...

239